Could we please have some Javadocs?
ePaul opened this issue · 8 comments
Most of the classes/interfaces/methods in this library have no Javadoc. This leaves my to guess what they are actually doing.
There is a usage example in the README, but it doesn't say what it is doing.
Could at least the most important classes/interfaces like AccessTokenBuilder, AccessTokens, AccessTokenConfiguration get some Javadocs for the important methods?
We welcome PRs 😄
@hjacobs The problem is that for writing documentation one first has to know what these things are supposed to do. Due to missing documentation I don't know.
I guess I could try to reverse engineer this from the source code (I did this years ago for JSch), but this would likely take more time from me than from someone who wrote the code, or who designed the library.
Yes, documentation for this lib is a hot topic. I just met with @LappleApple and @jbellmann last week to discuss next steps we want to take, to improve this. There is the plan to add more test-cases that demonstrate usage scenarios, but also to add more docs, of course.
@harti2006 @jbellmann I just updated the README based on my chat with Andre and Joerg, but I think it still lacks what you're looking for, @ePaul. Here were the follow-up "to-do's" from Andre+Joerg:
need to add:
-- main dependency to the credentials directory and credential files, or do a small unit test to show how to use it
-- Under ‘Usage,” example with two different tokens with two different scopes. It’s a minimum configuration.
-- a test case with the “test credentials” in JSON files, that uses the normal setup, and mock the OAuth provider with some mock REST service
-- show how we use it with one example
-- document more config options
@ePaul @hjacobs @jbellmann @duergner @harti2006 Hm, so, these Javadocs have been on the request list for some time. What can we do to get them created? :)
They are merged to master. I suppose we would just have to create a release to get them pushed to Central
👍 to that, @duergner ...
Fixed with latest release.