Details
-
Improvement
-
Status: Open
-
Minor
-
Resolution: Unresolved
-
None
-
None
-
None
Description
This is an ongoing meta-issue for improving the state of documentation in Jackrabbit. After a long history of following the maturing JSR 170 specification, the Jackrabbit codebase contains many parts that would benefit from better documentation. This issue is a call to arms for a community effort to improve the Javadoc documentation of Jackrabbit.
By this issue, you have an open mandate to improve the Javadoc documentation of any relatively stable part of Jackrabbit (no major changes during the last few weeks). You are free to contribute even partial and cursory documentation. Just follow the instructions below!
Instructions for non-committers:
If you want to help in improving the Javadoc documentation of Jackrabbit, please send your improvements as attachments to this issue. The best way to do this is to first check out the Jackrabbit source tree using anonymous Subversion, then make the Javadoc improvements you like, and finally use "svn diff" to generate a diff file that contains all your changes. You can then attach the diff file to this issue by following the "Attach file" link in the sidebar. Please remember to grant us the rights to include your changes (use the ASF grant option on the upload page). You may also want to write a short summary comment about the Javadoc improvements you made.
If you want to make changes also to the Jackrabbit code, then please send your changes to another issue. This issue is reserved only for Javadoc improvements.
Instructions for committers:
Please label your Javadoc commit messages with the Jira key (JCR-73) of this issue to mark the changes as document-only. This way other committers won't need to check your changes for bugs or other unexpected side-effects. Please follow the same guidelines also when committing Javadoc changes sent by non-committers.
This issue should remain as an unassigned and open issue at least for now. If this approach turns out to complicate Jira reports, then we can switch to another mechanism for handling Javadoc improvements. In that case this issue should be closed with a comment that explains the changes.