Hi,
It is time to talk more about everyone's favorite topic....code documentation!
I would like to work on improving the package documentation in hps-java. This should be one of the primary sources for high-level documentation about the software framework.
I have added package-info.java files to all the major packages in hps-java. Most of them did not have this.
The package documentation should have a simple header about what the classes in the package do, some amount of text describing this in more details, an author tag and also optionally
links to the more important classes or sub-packages.
For instance, here's the package-info.java file for the main conditions package.
/**
* Database conditions system
* <p>
* The HPS conditions module provides facilities for accessing time dependent conditions for a detector at runtime using
* a framework built on the LCSim conditions system. The {@link DatabaseConditionsReader} has a set of converters for
* reading data from tables using SQL queries and creating appropriate, typed objects for them.
*
* @author Jeremy McCormick, SLAC
* @see org.hps.conditions.api
* @see org.hps.conditions.database
*/
This doc will be included in the Javadoc that is automatically generated using Maven. The first line before the <p> tag is effectively a header that will show up in the package index. The documentation should follow standard Javadoc format which is basically HTML plus a set of specials tags like "{@link}". Indviduals with the low-level knowledge of the code will need to contribute here to provide the more detailed documentation.
This approach seems preferable to having external Confluence pages on our main classes and packages, because it is more convenient to have the primary code doc within the .java files themselves. It seems unlikely that external documentation will be updated as changes are made to the code but this is pretty easy to do if the doc is right there in the SVN.
I'm going to assign JIRA tasks to individuals who I think should provide documentation for individual packages in hps-java. Once I've done this, if you feel that a task has been misassigned (e.g. you're not capable or willing to write the package doc for it), please let me know and we'll assign it to another individual.
If you have any questions about this process, including basic ones about how to format your documentation or generate the javadoc locally for our projects, then please ask (likely that someone else probably has the same question).
And BTW please set your max line length in comments to 120 in your IDE.
Thanks.
--Jeremy
########################################################################
Use REPLY-ALL to reply to list
To unsubscribe from the HPS-SOFTWARE list, click the following link:
https://listserv.slac.stanford.edu/cgi-bin/wa?SUBED1=HPS-SOFTWARE&A=1
