Improve API documentation

[jaguililla]

This task is going to be open until release 2.0.0, at that point a full review of all code base will be performed.

IMPORTANT: Version 2 will have very deep changes, so some modules will be completely rewritten, it is safe to work on hexagon_core for this task, but for other modules, please contact me first.

If you find some public element (class, method, field, etc.) without proper API documentation, feel free to make the PR and reference this issue. However, the issue won't be closed as stated before.

ONLY public members require documentation.

Some hints to write the comments are:

• Use the imperative form.
• Capitalise descriptions (parameters, receivers, return types, etc.) and end sentences with a dot.
• Complete all KDoc tags (I.e.: @param, @receiver, etc. for the methods that have them.
• Focus on what they do, not how, neither what it is.
• Not saying method or property (that is clear from the context).
• Comments to ignore warnings (false positives) should include an explanation.
• Explain corner cases, default values and allowed values/formats if it applies.
• These are recommendations, feel free to make an exception if you think it is required to explain the use/structure of the code better.

This will make users learn how to use this tool much faster.

Thank you for making this library a bit better :)

[sumitkp18]

Hi @jaguililla , I am a first time contributor. Can I take this task up?

[sumitkp18]

I am unable to build the project. Getting the following error: e: /Users//StudioProjects/hexagon/build.gradle.kts:13:29: Unresolved reference: nullOutputStream

[jaguililla]

Thanks for contributing! You need to set up a JDK11 (nullOutputStream is available for JDK11+). Check contributing.md for all details. And if you need to do anything else not listed there... don't miss the chance to update contributing.md itself :)

[sumitkp18]

Thanks @jaguililla . Have setup the project with JDK11. I have started documenting the project. Completed JettyServerAdapter. Could you please assign this issue to me?

How do you want the PRs for the documentation? PR per module is fine?

Also, do we have any branching strategy or branch naming rules? The merged PRs were from develop so couldn't get an idea. I am planning to go with for documentation/<module_name> if that's fine. Please let me know.

Thanks.

[jaguililla]

I'll assign it to you, however, note that it is a long task and it doesn't matter if you finish it or not (it is a continuous background tasks until 2.0 release).

A PR per module is fine, but as some of them are big, you can also make PRs per package.

After proceeding with documenting, take a look to ongoing tasks to avoid conflicts with other PRs (btw, I'm working on the hexagon_core module now).

There is no branch naming standard, but the PRs should be done to develop (as master is reserved for releases).

Thanks for collaborating!

[sumitkp18]

Thanks @jaguililla . I will raise my PR for the http_server_jetty module. Please help me with your PR comments if any changes are required in my style of Java docs so that I can follow the same in other PRs too.

Thanks.

[sumitkp18]

@jaguililla Can you please help me with my first PR. I have forked the hexagon repo and while pushing I am getting a Build Error

Task :cleanDocker FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':cleanDocker'.
> A problem occurred starting process 'command 'docker''

* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output. Run with --    scan to get full insights.

* Get more help at https://help.gradle.org

BUILD FAILED in 3s
1 actionable task: 1 executed
error: failed to push some refs to 'https://github.com/sumitkp18/hexagon.git

[jaguililla]

You'll need Docker installed... you can take a look at the contributing guide. And ask again if it doesn't solve your problem (in that case, I'll help you and update the guide). Thanks!

[sumitkp18]

I have docker installed. I now tried to run the following command given in contributing guide: ./gradlew setUp build buildSite publishToMavenLocal

and it gives me the following error:

Dependency verification is an incubating feature.

Task :setUp Client: Docker Engine - Community Cloud integration 0.1.18 Version: 19.03.13 API version: 1.40 Go version: go1.13.15 Git commit: 4484c46d9d Built: Wed Sep 16 16:58:31 2020 OS/Arch: darwin/amd64 Experimental: false

Server: Docker Engine - Community Engine: Version: 19.03.13 API version: 1.40 (minimum version 1.12) Go version: go1.13.15 Git commit: 4484c46d9d Built: Wed Sep 16 17:07:04 2020 OS/Arch: linux/amd64 Experimental: false containerd: Version: v1.3.7 GitCommit: 8fba4e9a7d01810a393d5d25a3621dc101981175 runc: Version: 1.0.0-rc10 GitCommit: dc9208a3303feef5b3839f4323d9beb36df0a9dd docker-init: Version: 0.18.0 GitCommit: fec3683 docker-compose version 1.27.4, build 40524192 docker-py version: 4.3.1 CPython version: 3.7.7 OpenSSL version: OpenSSL 1.1.1g 21 Apr 2020

Task :http_client_ahc:test

com.hexagonkt.http.client.ahc.AhcAdapterExampleTest > JSON requests works as expected() FAILED java.lang.AssertionError at ClientTest.kt:96

11 tests completed, 1 failed

Task :http_client_ahc:test FAILED

FAILURE: Build failed with an exception.

• What went wrong: Execution failed for task ':http_client_ahc:test'.

There were failing tests. See the report at: file:///Users/sumit6975/StudioProjects/hexagon/http_client_ahc/build/reports/tests/test/index.html

• Try: Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output. Run with --scan to get full insights.

• Get more help at https://help.gradle.org

BUILD FAILED in 27s 55 actionable tasks: 3 executed, 52 up-to-date

[sumitkp18]

All tests of ClientTest class pass successfully if the test is run independently on the class.

[sumitkp18]

I was able to run the command successfully on removing the test annotation from the following method in ClientTest class:

fun JSON requests works as expected()

I also got a docker file generated after the build was successful, should it be put in .gitignore ?

[jaguililla]

What file is being created?

[sumitkp18]

Sorry, that file was my mistake. I had tried to create a symlink of docker binary in the repo temporarily, as I was getting the error:

A problem occurred starting process 'command 'docker''

Could you please help me with the build error as well as the error on pushing the changes?

[sumitkp18]

@jaguililla I was using Sourcetree app to handle git, and perhaps it wasn't able to resolve docker binary.

I tried pushing it through terminal and it worked. I have pushed the changes. Will raise PR.

[sumitkp18]

@jaguililla I have addressed the review comments and updated my PR. Could you please check.

[jaguililla]

I made two minor comments and with those it will be done 🙂

[sumitkp18]

Addressed the comments and pushed the changes.

[jaguililla]

Merged! Now you've warmed up... Wouldn't you like to pick another module ;)

[sumitkp18]

Sure @jaguililla Thanks a lot for guiding me. This is my first Open Source contribution! Feeling awesome!

[sumitkp18]

Starting with port_http_server module. Sorry for the long break, had been busy with work.

[jaguililla]

No worries, I understand (that was my situation some days ago) 🙂 Thank you for your contribution, don't press yourself, relax and enjoy!

[sumitkp18]

@jaguililla , can you please help with the RequestHandler class. I am not getting a clear idea on the different child class handlers.

[sumitkp18]

I was able to get some understanding by observing test implementations. Have added the docs accordingly; will modify if required, after review.

[sumitkp18]

@jaguililla I have raised a PR for documentation of port_http_server module. Please review.

[jaguililla]

Reviewed with a few comments :)

[sumitkp18]

Addressed the comments @jaguililla . Thanks.

[jaguililla]

Thanks to you 🙂

[MohamedHarmoush]

Hi @jaguililla I am a first-time contributor. If it doesn't bother you, could you guide me with modules that need to get documented?

[jaguililla]

Hello @MohamedHarmoush and thank you for your interest in this toolkit, the best module to start would be Hexagon Core.

The helpers package already contains some documentation (you can read some of the comments to use the same style).

Before considering picking another module, ask me... I'm working on version 2 and will have very deep changes, so some modules will be completely rewritten.

Thanks again for your support, and if you have any doubt, just contact me :slightly_smiling_face:

[MohamedHarmoush]

Hello, @jaguililla thanks for your reply. I'll read the documentation of the helpers package then start with the core module documentation as soon as possible and it doesn't bother you, I will let you know if I faced any problems can't solve them.

Thanks in advance for your support. Keep going with the good job you do 🙂.