How to generate documentation using Java documentation comments?

We know that Java supports three types of comments, namely single-line comments, multi-line comments and document comments. Let’s take a look at what they look like

//Single-line comments

/*
Multi-line comments
*/

/**
*@...
*....
*Documentation Comments
*/

Maybe many newbies don’t understand what is the use of writing these comments Woolen cloth?

In fact, it is because beginners have a small amount of code and can quickly find and modify it without comments

When the code gradually increases, comments are a good thing, not only for themselves to be clear Seeing the code clearly is also for the convenience of the members who develop the project with you

Remember, get rid of the bad habit of not writing comments! ! !

So, here comes our topic today, what are Doc comments?

Javadoc is a technology provided by Sun. It extracts comments such as classes, methods, members, etc. from the program source code to form an API help document that matches the source code. In other words, as long as you use a specific set of tags to annotate the program when writing the program, after the program is written, the development documentation of the program can be formed at the same time through Javadoc.

The javadoc command is used to generate API documents. How to use it: Use the command line to enter javadoc file name.java in the directory where the target file is located. java

You don’t have to get entangled with these complicated theories, you need to cultivate a kind of thinking. , to understand, to understand, to go deep, to change it, to understand it, and clinging to the theory will have no effect!

When we write code, there are standards. If the code you write can run, but it is a mess, no one is willing to use it because it is difficult to maintain. Therefore, the code is not just a simple program. The online world, I prefer to call it a work of art, requires your careful engraving

Some people may say, isn't it just annotation? What's wrong with this

However, this Doc comment is not the same as the other two comments. There are also standards for comments!

Doc comment specifications

Format:

Document comments written on the class are generally divided into three paragraphs:

The first paragraph: summary description, usually Briefly describe the function of this type in one sentence or a paragraph, ending with an English period

Second paragraph: Detailed description, usually use one or more paragraphs to describe the function of this type in detail, usually each paragraph ends with End with an English period

The third paragraph: Document annotation, used to mark the author, creation time, reference class and other information

Here I want to expand a little knowledge, our Doc comments can use the Dos command Or the IDE tool generates a Doc document. This document is written in HTML language, so some simple HTML codes can be included in the comments, such as the following

Line breaks

Segmentation

(written before the paragraph)

Put an example style diagram:

The use of @symbol

When we write Doc comments, press Enter directly after /**, and the following comment frame and some @ symbols will be automatically generated. So what is the use of these @ symbols?

##@authorIdentifies a class The author, generally used for class annotations @author description@deprecated designates an expired class or member and indicates the class or method It is not recommended to use @deprecated description{@docRoot}Indicate the path of the current document root directoryDirectory Path@exceptionExplanation of exceptions that may be thrown, generally used for method comments@exception exception-name explanation{@inheritDoc}Inherits a comment from the immediate surperclass.{@ link}Insert a link to another topic{@link name text}{@linkplain} Inserts an in-line link to another topic.@paramDescribe the parameters of a method, generally used for method comments@param parameter-name explanation@returnDescribe the return value type, Generally used for method comments and cannot appear in construction methods@return explanation@seeSpecify a link to another topic@see anchor@serialDescribe a serialization attribute@serial description@serialDataDescribe the data written through the writeObject() and writeExternal() methods@serialData description@serialFieldDescribe an ObjectStreamField component@serialField name type description@sinceIndicate from which version this function has been included@since release@throwsThe @throws tag has the same meaning as the @exception tag.{@value}Display the value of the constant, which must be a static attribute. Displays the value of a constant, which must be a static field.@versionSpecifies the version of the class, generally used for class annotations @version infoWe said above that after writing Doc comments, we can generate a Doc document, and it is in HTML format, so how do we generate it?

Tag	Description	Example
	@The following part is in English, you can write in Chinese, such as @author Xiaojian	How to generate Doc Document

First: Dos command generation

javadoc [options] [packagenames] [sourcefiles]

Description of format:

options

represents the options of the Javadoc command;

packagenames

represents the package name;

sourcefiles

represents the source file name;

Enter javadoc -help

in cmd (command prompt) to see the usage and options of Javadoc (provided that JDK is installed and configured). Common options of the Javadoc command are listed below:

NameDescription

-publicDisplay only public classes and members-protectedShow protected/public classes and members (default)-package Show package/protected/public classes and members##-private-d -version- author-splitindex-windowtitle Generating it with Doc is troublesome and slow. Is there any other way? Woolen cloth? Second: IDE tool generationWe can use Eclipse or IDEA to generate it. I don’t use Eclipse very much. Let me demonstrate it to you using IDEA!

Show all classes and members
Destination directory for the output file
Contains the @version section
Contains the @author segment
Split the index into one file for each letter
The browser window title of the document

In the JavaDoc inside the tool, it looks like this after entering it

The output directory must be selected, otherwise it will be generated No,

, please note, because the coding of Java is different from that of IDEA, so in the other command parameters column, you need to fill in the following content

-encoding utf8 -docencoding utf8 -charset utf8

After generation, it will look like this

The above is the detailed content of How to generate documentation using Java documentation comments?. For more information, please follow other related articles on the PHP Chinese website!