Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Javadocs to hosted GitHub docs #421

Open
mattmetlis opened this issue Aug 23, 2019 · 8 comments

Comments

@mattmetlis
Copy link
Collaborator

commented Aug 23, 2019

Hosting the Javadocs on GitHub (in addition to the guide which is already hosted) would be helpful for understanding how to use WebTau.

@MykolaGolubyev

This comment has been minimized.

Copy link
Collaborator

commented Aug 23, 2019

I wonder if we should add reference section to the docs themselves.
I am not a big user of javadocs, so curios what kind of information you are looking for mostly.

@mattmetlis

This comment has been minimized.

Copy link
Collaborator Author

commented Aug 23, 2019

The primary thing that led me to this request is that I find myself frequently using IntelliJ to click through to the methods I'm calling in my tests to see what different combinations of arguments I can pass. Primarily the post, put, get, etc., but also the assertion methods and methods on the data nodes.

The advantages of javadocs are that they can be generated directly from the source code so they stay in sync, and they're self linked so fairly easy to navigate. The downside is it will show classes that you might not want users using directly, though if there's a good reason for them not to then they probably should be protected in some other way. My concern with a reference section in the existing guide is I think it would have to be manually kept in sync.

@MykolaGolubyev

This comment has been minimized.

Copy link
Collaborator

commented Aug 23, 2019

We use Znai for docs and it is using references to the code and real examples with the purpose of it not to become stale.

I am for JavaDocs to be up-to-date as well. In fact Znai can reference text of java docs and embed it inside the user guide.

I think we should have both, with the focus on making official user guide to be easier to follow.

@mattmetlis

This comment has been minimized.

Copy link
Collaborator Author

commented Aug 23, 2019

That's good to know, I had missed that feature of Znai. It looks like you can reference specific methods or specific docs, but (unless I missed something) answering for the user 'what are all the different overloaded versions of this method' or 'what are all the methods I can call on this class' might be best answered with Javadoc. The Znai inclusion would be useful for providing examples in the guide.

@mattmetlis

This comment has been minimized.

Copy link
Collaborator Author

commented Aug 23, 2019

By the way, would it make sense to define the various config keys as a list of constants in one place?

@mattmetlis mattmetlis closed this Aug 23, 2019
@mattmetlis mattmetlis reopened this Aug 28, 2019
mattmetlis added a commit to mattmetlis/webtau that referenced this issue Aug 29, 2019
@mattmetlis

This comment has been minimized.

Copy link
Collaborator Author

commented Aug 29, 2019

I created a pull request for generating the javadocs. @tsiq-karold is there any automation right now around the user guide or other docs that I should integrate this with, or is it all manual right now?

@tsiq-karold

This comment has been minimized.

Copy link
Collaborator

commented Aug 29, 2019

There is some. https://github.com/twosigma/webtau/blob/master/update-gh-pages.sh will update the gh-pages branch with znai generated docs and the znai export. Modifying it to also add javadocs should hopefully be fairly easy.

The intention was to run that from a release build hence the deploy part in the Travis file: https://github.com/twosigma/webtau/blob/master/.travis.yml#L25

However, getting the permissions to work correctly is likely to be more pain than it's worth so I'm going to remove that from Travis and update https://github.com/twosigma/webtau/blob/master/release.md to say run that script.

mattmetlis added a commit that referenced this issue Sep 15, 2019
#421 adding generation of javadocs
@mattmetlis

This comment has been minimized.

Copy link
Collaborator Author

commented Sep 15, 2019

I've merged the change to be able to generate the javadocs. Will keep this open until I can add them to the update-gh-pages script.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.