One of the nice things about sphinx and python is the relatively simple coupling between API documentation and explanatory documentation in markdown using chapters and sections that give the background and examples. Is there a way to do this in Java using javadoc, sphinx or some other library that has general community traction?
2 Answers
Javadoc absolutely does support this.
Internal documentation can be included in the special subdirectory doc-files under any package. The javadoc tool will always copy doc-files subdirectories into generated documentation file trees, making them stable sources to which class (and package) javadoc can link using relative paths. All javadoc content is HTML, so ordinary <a href="…"> elements are sufficient.
Examples:
- The java.awt package documentation links to in-depth Focus Subsystem documentation and in-depth modality documentation, both included in Java SE in a doc-files subdirectory.
- The javax.imageio package documentation links to full descriptions of metatadata for the image formats its supports, all located in a doc-files subdirectory.
- Many security classes’ documentation will link to a table of standard algorithm names. For example, KeyStore links to a table of standard keystore types, with descriptions of each. This document is part of the Java SE javadocs.
External links can be placed in @see or @spec tags, like this:
/**
* This is a description of a package or class or class member.
*
* @see <a href="https://example.com/docs/concepts/">General concepts explanation</a>
* @spec https://example.com/standard/myprotocol/ My protocol specification
*/
- The Math class contains an external link to the IEEE floating point standard.
- The Locale documentation uses
@specto refer to language tag specifications. - The java.util.zip package documentation links to full specifications related to zip and gzip compression.
If you’re looking for tutorials and examples, many Swing classes have such links. For example:
- The JTable documentation’s first paragraph links to the “How to Use Tables” section of the Java tutorial.
- The JFileChooser documentation’s first paragraph links to the “How to Use File Choosers” section of the Java tutorial.
There are many more links to in-depth documentation in Java SE. The above ones are just some that I remembered off the top of my head.
Comments
Integrate Javadoc Links: Link to your Javadoc-generated API documentation within your explanatory documentation using intersphinx references. For example:
:java:package:: com.example
:java:module:: com.example.mymodule
:java:method:: MyClass.myMethod(param1, param2)
1 Comment
Eli S
Thanks for adding this comment. I accepted the answer from @VGR because it is great set of examples that better explains the boundaries of javadoc. However, sphinx is still a much more powerful tool and when I need that I'll be re-visiting your answer.
<pre><code>HTML elements, or{@code}and, in more recent versions,{@snippet}taglets. You can explain the purpose of the API and some reasons for using it. You can use package-level or even module-level Javadoc for more general documentation. Whether any of this is done depends on how much effort is put into the it; even in the standard library, not everything has the same level of documentation