libelektra
libelektra copied to clipboard
ElektraInitiative
Improve Javadoc [JNA bindings]
Since properly updating the Javadoc for the JNA bindings is quite time consuming, I'm creating this issue to track the task separately.
- [x] Update API consumer Javadoc
- ~~[ ] Update internal API developer Javadoc~~
- [x] reactivate strict Javadoc checks in
java-shared.gradle
Thank you for creating the issue!
Where do we want to publish the javadoc? Also on doc.liblektra.org?
Maybe we cheat a little bit and tell students to look at the master API doc (you will update), even if they use 0.9.5? (This would work if you only update doc and do not change the API.)
Do we need "internal API developer Javadoc"? In Elektra we stopped building it because nobody used it.
Where do we want to publish the javadoc? Also on doc.liblektra.org?
Maybe we cheat a little bit and tell students to look at the master API doc (you will update), even if they use 0.9.5? (This would work if you only update doc and do not change the API.)
When publishing to maven central, 3 jars are being published: binaries, sources and javadoc IDEs can then automatically link the source and docs for the libelektra dependency
Ok, but they don't publish it on a website? So this we need to do ourselves?
Do we need "internal API developer Javadoc"? In Elektra we stopped building it because nobody used it.
From my experience the best rule of thumb is: every non-(package-)private interface, class, member or method needs at least basic documentation. Documentation should be concise. Of course there are instance where exceptions to this rule can be sensible.
Since API binding developers are also developers and a healthy fluctuation of developers working on the JNA binding is to be expected in the future, i would argue internal API developer javadoc is quite as important as public API javadoc.
Since API binding developers are also developers and a healthy fluctuation of developers working on the JNA binding is to be expected in the future, i would argue internal API developer javadoc is quite as important as public API javadoc.
I agree but unfortunately we cannot maintain two different descriptions of the API and the API is currently being reworked to be fit for 1.0. So we really should avoid duplication of this documentation. After 1.0 the docu can be copied.
Again by accident? If you write "see #3754" (or similar) PRs won't be closed.
I will try to activate strict java doc checking in gradle build, which should close this issue.
Yes, java docs are part of building the Java binding artifact (also necessary for maven upload).