NetBeans and Eclipse export Javadoc documents

One, note (1) Formatting of document annotations

The generated documents are in HTML format, and these HTML format identifiers are not Javadoc, but we write them when we write the comments. For example, instead of typing a carriage return, you would write
if you want to break a line, and you should write

Before the segment if you are segmenting.

Therefore, formatting the document means adding the appropriate HTML identifier to the document comment.

The body of the document comment is not copied directly to the output file (the document's HTML file), but after each line is read, the leading * number and the previous space of the * number are deleted and then entered into the document.

Such as

/** * This was first line. 
*/  

After compiling the output, the HTML source code is the this is first line. 
This was second line.
This was third line.

The leading * number allows for continuous use of multiple, with the same effect as using a * number, but there can be no other characters separated by multiple * numbers, otherwise the delimiter and subsequent * numbers will be the contents of the document.

It is also important to note that the documentation comment only describes the class, property, or method immediately following it, such as:

/***/public    classtest {}

(2) Three parts of document comments

The document comments are divided into three parts, depending on the effect shown in the document. Let's give an example to illustrate this.

/** * Summary of the Show method * 
 Detailed description of the Show method the first line 
 * Detailed description of the Show method the second line @param b true to show, false to hide the c7/>@return  no return value   */public void Show ( boolean  b) {    Frame.show (b);}

1. The first part is a summary

The description after the attribute name or method name in the list is a summary. A brief description is written before the first dot (.) in a document comment, including the point number. In other words, the document comments are separated by the first dot, preceded by a brief description, followed by the second and third parts. As in the example above, "* The description of the show method."

Sometimes, even if a dot is correctly delimited, Javadoc will still go wrong, and the part behind the dot is also done for the first part. To solve this problem, we can use a

flag to separate the second part, as in the previous example, the "*

Show method details the first line ...".

2. Part Two is a detailed description

This section describes the properties or methods in detail, there are no special requirements in the format, and can contain several dot numbers.

3. Part III is the Special description section

This section includes release notes, parameter descriptions, return value descriptions, and so on. In the third part, the corresponding code in the example above is:

* @param b True indicates display, false means hidden

* @return No return value

In addition to the @param and @return, there are other special tags for descriptions of classes, properties, and methods, respectively.

Quick Note Writing tips: Enter "/**" before comments or method comments, press ENTER, the development software will automatically param and return to help you to load out, only with the function of the corresponding parameters can be introduced, it is recommended that the programmer in the process of development will write the comments well, To form a good programming habit.

(3) Use Javadoc mark

Javadoc tags are special tags that are inserted into document comments that identify special references in your code. The Javadoc tag consists of the tag type and the private comment reference followed by "@". Remember, three parts--@, tag type, private comment reference. While the @ and tag types can sometimes be separated by spaces, it is recommended to write them next to each other to reduce the chance of error.

The Javadoc tags have the following:

Tags for action

@author description of the class indicates the author of the development of such a module

@version the description of the class indicates the version of the class module

@see a reference to the description of classes, properties, methods, and related topics

Description of a parameter in a method @param description of the method

Description of the method return value @return The description of the method

@exception the description of the method, describe the exceptions that the method might throw

1. Use of @see

There are three types of syntax for @see:

@see class Name

@see #方法名或属性名

@see Class Name # Method name or property name

Cases:

/**   * @seejava.lang.String *@see#str *@see#str () *@see#main (string[]) *@seejava.lang.object#tostring () */   PublicClasstestjavadoc {PrivateString str; Publicvoid Str () {} Publicstatic void Main (string[] args) {}}

2, the use of @author, @version description class

These two tags are used to indicate the author and version of the class. By default Javadoc ignores it, but command-line switches-author and-version can modify this feature so that the information it contains is output.

The syntax for these two tokens is as follows:

@author Author name

@version version number

Where @author can be used multiple times to indicate multiple authors, separated by commas (,) between each author in the resulting document. @version can also be used more than once, only the first time it is valid, the resulting document will only show the version number indicated by the first use @version. The following example

/**       @author MK * @versionVersion 1.00 * * Public     Class Testjavadoc {}

3. Instructions for using @param, @return and @exception

These three tokens are used only for methods. @param describes the parameters of the method, @return describes the return value of the method, @exception describes the exception that the method might throw. Their syntax is as follows:

Parameter description of the @param argument name

@return Return Value Description

@exception Exception class name description

Each @param can only describe one parameter of the method, so if the method requires more than one parameter, it needs to be described multiple times using the @param.

Only one @return can be used in a method, and if more than one @return is listed in the document description, a warning is issued Javadoc compile, and only the first @return is valid in the resulting document.

The exceptions that the method may throw should be described in @exception. Because a method may throw multiple exceptions, you can have multiple @exception. Each @exception should have a description of the exception class name, which should indicate why the exception was thrown. It should be noted that the exception class name should be based on the import statement of the source file to determine whether to write out the class name or class full name.

Examples are as follows:

 Public classTestjavadoc {/**  * @paramn a switch *@paramB excrescent Parameter *@returntrue or False *@returnexcrescent return *@exceptionjava.lang.Exception Throw when switch is 1 *@exceptionnullpointerexception Throw when parameter n is null*/  Public BooleanFun (Integer N)throwsException {Switch(N.intvalue ()) { Case0:  Break;  Case1: Throw NewException ("Test only")); default: return false; } return true; }}

Second, the development of software to generate Javadoc method (1) NetBeans export Javadoc method:

Select the project name--right-click and build Javadoc to complete the production documentation

(Document General path in: Under the Dist folder under the project name under the Doc folder)

(2) Eclipse generates the Javadoc method:

Select the project name-right-click-->export, select "Javadoc" under "Java", click "Next", and in the text box under Javadoc command find the Javadoc.exe under the path of the JDK (for example, C: \ Program Files\java\jdk1.7.0_25\bin\javadoc.exe)

Click "Next" in the document title to name the documents you want (for example: Project name +doc), click "Next" in "Extra Javadoc options (...)" option, enter "-encoding UTF-8-charset UTF-8" (this is mainly used to solve the garbled problem), click "Finish" to complete the document generation

(Document General path in: Under the Doc folder under project name)

(3) Javadoc command generation Javadoc method

Run: Javadoc-help can see the use of Javadoc, here are the following list of common parameters:

Usage: Javadoc [options][packagenames] [SourceFiles]

1. Option options:

-public Show only public classes and members

-protected display Protected/public classes and members (default)

-package displaying package/protected/public classes and members

-private Show all classes and members

-D The destination directory of the output file

-version contains @version segments

-author contains @author segments

-splitindex divides the index into one file per letter

-windowtitle the browser window title of the document

2, Javadoc compile the document can be given a list of packages, you can also give a list of source program files

For example: Under CLASSPATH There are two packages of several classes as follows:

Mk. Editor

Mk. Test

Mk.editor.Command

Mk.editor.Document

Mk.editor.View

1) There are two packages (MK and Mk.editor) and 5 classes. Then compile-time (Windows environment) can use the following Javadoc command:

Javadoc Mk\test.java Mk\editor.java Mk\editor\command.java Mk\editor\document.java Mk\editor\view.java

This is to give the Java source file as a method of compiling parameters, note that the command points to the file path, should be changed according to the actual situation.

2) It is also possible to give a package masterpiece as a compilation parameter, such as:

Javadoc Mk Mk.editor

3. Detailed Options option

-public,-protected,-package,-private four options, you only need to select one. They specify the degree to which the class members are displayed. The number of members they display is a contained relationship, as follows:

-private (Show all classes and members)

-package (show Package/protected/public classes and members)

-protected (show Protected/public classes and members)

-public (Show public classes and members only)

The-D option allows you to define the output directory. If you do not define the output directory with-D, the resulting document file is placed in the current directory. The use of the-D option is

-D directory Name

The directory name is required, meaning that if you use the-d parameter, you must specify a directory for it. This directory must already exist, and if it does not exist, create the directory before running Javadoc.

-version and-author are used to control whether @version and @author specified content are generated when the document is generated. Without these two parameters, the resulting document does not contain version and author information.

The-splitindex option divides the index into one file per letter. By default, the index file has only one, and the file contains all indexed content. Of course it's a good thing to do when you don't have a lot of document content, but if the content of the document is very large, the index file will contain a lot of content. Using-splitindex, the index file is categorized by the first letter of each index entry, and each letter corresponds to a file. This reduces the burden on an index file.

The-windowtitle option assigns a caption to the document, which appears on the title bar of the window. If you do not specify the caption, the default document title is "generated document (untitled)". The use of this option is:

-windowtitle Title title is a string of text that contains no spaces, because whitespace is used to separate parameters, so it cannot contain spaces. Similar to-D, if you specify the-windowtitle option, you must specify the caption text.

NetBeans and Eclipse export Javadoc documents