Generate project documentation with JavaDoc

At the end of the project, everyone started to have a headache - again to write the documentation... Yes, most of us didn't train as a regular Programmer. When I first learned to program, I never thought about writing a complete document for the programs I wrote. All the comments were just for me to remember what the code was doing at the time. No one thought about it. Through the upgrade and sharing of these codes. However, after starting commercial software, everything changed, especially in large team development projects.
 As you may have noticed, the Java API documentation is always kept up to date with the latest version of the JSDK. Just imagine, is it possible to maintain such a complex document manually? Of course not, all of this is due to the small program javadoc (of course, there are also java class library authors who do program comments). The API documentation is automatically generated based on the latest source code, and everything is so easy - you just need to write more standard and a little more detailed comments that you would have written. However, people seem to be unaware of its existence, and few people use it to document their programs. I don't know, are you interested in it now? Well, let's start this easy automatic document generation journey.

 [How to insert comments]

 JAVADOC does not generate code for you out of thin air, nor does it automatically analyze your code - everyone has their own code style, if you want to analyze and translate, I am afraid that machine code is a hundred times easier to generate. Its analysis mechanism relies on you to annotate your code properly and enough according to the specification. Only when you write your notes honestly can you do the work that you used to do twice.
 The Javadoc tool can extract information from the following objects:
 · Packages.
 · Public class.
 · Public interface.
 · Public or protected methods.
 · Public or protected variables/constants.
 For each feature, you should provide a comment. Every comment must start with /** and end with */. You can include text in any format in each /**...*/ documentation comment. , its first sentence should be a concluding sentence, and javadoc will automatically bring it up to make a summary page. Of course, you can use some HTML notation here, such as ... for italics; <tt>...</tt> for monospaced "printer" fonts; .. . for bold; even use <img...> to include an image, etc. (But don't use tags like <h1> for heading formatting, or horizontal dividers <hr>, etc., which would conflict with the document's own formatting) Then follow with some special "tags". Each tag starts with @, such as @author or @param, etc.
 Adding links to other files in comments (such as your illustrations and pictures) requires placing those files in a subdirectory called doc-files. javadoc will copy these directories and the files in them from the source directory to the documentation directory. Below we categorize and explain some of the tags we may use more frequently.

 ■General Comments
 The following tags can be used in all documentation comments.
 ◇ @since version
 This tag can generate a comment indicating which version of the software this feature (class, interface, property or method, etc.) is provided after.
 ◇ @deprecated class, attribute, method name, etc.
 This tag can add a comment, indicating that the corresponding class, method or attribute should no longer be used. javadoc only copies the first sentence into the overview section and index. The latter sentence can also explain why its use is discouraged. Sometimes, we also recommend another solution, for example:
 @deprecated Use <tt>theAnotherMethod<
 Or tag a suggested link with {@link} and we'll cover its use shortly.
 ◇ @see link
 This tag adds a hyperlink to the "See also" section. The link here can be any of the following:
 · package.class#member label Adds an anchor link to the member, preceded by a space with the target of the hyperlink followed by the displayed text. Note that # is used to separate a class and its members instead of a dot. You can omit the package name or even the class name. The default refers to the current package and class, which makes comments more concise, but the # sign cannot be omitted. label can be omitted.
 · <a href=...>label</a> This needs no explanation.
 · "Text" This directly adds a piece of text without a link to "See also".
 ◇ {@link link target display text}
 Actually, to be precise, the usage of link is the same as that of see, see is to list the link in the reference item, and link is to directly embed a paragraph with super The text of the link.

 ■Add annotations to classes and interfaces.
 Class or interface annotations must be after all import statements and before the class definition. In addition to the general tags mentioned above, you can also use the following tags in class annotations:
 ◇ @author author name
 When using the author tag, add the "Author" (author) item in the generated document with the specified text. Documentation comments can contain multiple @author tags. One or more names can be specified for each @author. Of course you can also use multiple author tags, but they must be grouped together.
 ◇ @version version
 This tag suggests a "version" entry, followed by any description of the current version.
 Here is an example of a class annotation:
/**
* An implementation of a menu bar. You add <code>JMenu</code> objects to the
* menu bar to construct a menu. When the user selects a <code>JMenu< /code>
* object, its associated <code>JPopupMenu</code> is displayed, allowing the
* user to select one of the <code>JMenuItems</code> on it.
* 
* For information and examples of using menu bars see
* <a
href="http://java.sun.com/docs/books/tutorial/uiswing/components/menu.html">How to Use Menus</a>,
* a section in The Java Tutorial.

* <a href=doc-files/Key-Index.html#JMenuBar>JMenuBar</a> key assignments.
* 
* Warning:
* Serialized objects of this class will not be compatible with
* future Swing releases. The current serialization support is appropriate
* for short term storage or RMI between applications running the same
* version of Swing. A future release of Swing will provide support for
* long term persistence.
*
* @beaninfo
* attribute: isContainer true
* description: A container for holding and displaying menus.
*
* @version 1.85 04/06/00
* @author Georges Saab
* @author David Karlton
* @author Arnaud Weber
* @see JMenu
* @see JPopupMenu
* @see JMenuItem
*/

 ■A method annotation
 immediately precedes each method annotation and must have a signature of the method it describes. Also in addition to using general-purpose tags, you can also use the following annotations for methods:
 ◇ @param variable describes
 all parameters required by the current method, which need to be explained with this tag, and these tags should be put together. Specific descriptions (descriptions) can span multiple lines at the same time, and can use html markup.
 ◇ @return The return value of the method
 This tag adds a return value ("Returns") section to the current method. The same specific description supports html and can span multiple lines.
 ◇ @throws Exception thrown by this method
 This mark adds an entry in the "Throws" section for the current method, and will automatically create a hyperlink. The specific description can span multiple lines and can also include html tags. All throws of a method must be put together.
 The following is an example of a method annotation:
 /**
 * Returns the model object that handles single selections.
 *
 * @param ui the new MenuBarUI L&F object
 * @return the <code>SingleSelectionModel</code> property
 * @see SingleSelectionModel
 * @see JComponent#getUIClassID
 * @see UIDefaults#getUI
 */

 ■The preceding package and overview comments
 are comments for a certain class, method, etc., which can be placed directly in the JAVA source file. However, in order to generate a package annotation, a file called package.html must be placed in each package's directory to describe the package. The text between the tags <body>....</body> will be automatically extracted by javadoc.
 It is also possible to provide an overview comment for all source files, written in a file named overview.html, placed under the parent directory where all source files are located. The text between tags <body> .... </body> will also be automatically extracted by javadoc to make an overview of the document

 [How to extract program documentation]

 First of all, let's take a look at the basic usage of javadoc according to convention. The specific setting details of its current version can be obtained through javadoc -help.
 javadoc [options] [packagename] [sourcefiles] [@files]
 Parameters can be arranged in any order.
 · options Command-line options.
 · packagenames A list of package names, separated by spaces, must be specified separately for each package for which you want to document. Javadoc does not recurse to every package, nor does it allow wildcards.
 · sourcefiles A list of source file names, separated by spaces. Source file names can include paths and wildcard characters such as "*".
 · @files One or more files containing package names and source files in any order. It can be used to simplify the operation when there are too many files to specify in sourcefiles. Destination files are source file names separated by spaces or carriage returns.
 The commonly used options are:
 -d path
 specifies the destination directory where javadoc saves the generated HTML file, the default is the current directory.
 -author
 include author information in the document (omitted by default)
 -version
 include version information in the document (omitted by default)
 -header header text
 Specifies the header file to place at the top of each output file. The header file will be placed to the right of the upper navigation bar. The header text can include HTML tags and spaces, but if so it must be enclosed in quotation marks. Any inner quotes in the header must not be escaped.
 -footer footer text
 Specifies the footer text to place at the bottom of each output file. The script will be placed on the right side of the lower navigation bar, otherwise the same as the header.
 -bottom text
 specifies the text to place at the bottom of each output file. This text will be placed at the bottom of the page, below the navigation bar. Other same header parameters.
 -protected
 only shows protected and public classes and members, which is the default.
 -public
 only shows public classes and members.
 -package
 Only packages, protected and public classes and members are displayed.
 -private
 shows all classes and members, this is very useful if it is a program document used by internal development.
 -sourcepath sourcepathlist
 When passing the package name to javadoc, you can specify the search path to find source files (.java). It must be noted, however, that the sourcepath option can only be used when specifying a package name with the javadoc command. If sourcepath is omitted, javadoc uses classpath to find source files. Note: You need to set the sourcepath to the directory where the source files of the target package are located, for example: you have a package cn.com.linuxaid in c:jproject, and you want to generate documentation for the files in it, then you must write c:jprojectcncomlinuxaid.
 -clathpath clathpathlist
 specifies the path where javadoc looks for "referenced classes", which are the classes with the value documentation plus any classes they reference. javadoc will search all subdirectories of the specified path. classpathlist can contain multiple paths separated by semicolons.

 Let's take an example:
 Suppose, we need to place our generated documents in targetdocdir, and we need to create program documents for the source files in the cn.com.linuxaid package in c:jproject. Then we need to go to c:jprojectcncom (that is, the directory that contains overview.html - if you provide it). Then run javadoc -d targetdocdir cn.com.linuxaid

 In addition to javadoc providing a wealth of options and parameters to allow you to customize the program documentation you need to generate, you can also use doclet to generate any form of output. For specific situations, please read the online help documentation carefully.

Generate project documentation with JavaDoc

Guess you like