Blue wind

The project has come to an end, everyone has begun to take a headache - I have to write a document ... Yes, most of us are not trained from regular Programr. When I learned the program, I never thought about writing a complete document to I have written to myself. All the comments are just for my own code. No one wants. The upgrade of these codes, share the problem. However, after starting business software, everything has changed, especially in large team development projects.

Everyone may not be noted that Java's API document always keeps the latest state as JSDK's version is increased. Imagine, do you manually maintain such a complex document? Of course, it is impossible, all of which is the trigger of Javadoc (of course, there is also a credit for the Java class library). The API document is to be used automatically according to the latest source code. Everything is so easy - only you need to write the annotations you want to write more standard, and then more detailed. However, everyone seems to seem to be aware of its existence, very few people will use it to generate documents for their own programs. I don't know, is you interested in it now? Ok, let's start this relaxed document to generate a trip.

[How to insert a comment]

Javadoc is not as evacuation for you, nor it will automatically analyze your code - everyone has their own code style. If you want to analyze translation, it is prone to machine code is more easily generated. Its analysis mechanism depends on your code that you should add to your code in accordance with the specification. Only when you are always writing a comment, it is possible to make a job you need to do once again.

Javadoc Tools can extract information from the following objects:

· Package.

· D.

· Public interface.

· Public or protected methods.

· Public or protected variable / constant.

For every feature, you should provide a note. Each annotation must be headed in / **, with * / end. In each / ** ... * / document comment, the text can include any format. It should be a summary statement, and Javadoc will automatically bring it to make a summary page. Of course, here you can use some HTML markers, such as ... represents the bevel; ... represents the equationable "printer" font; .. Represents a bold; even use including a pair image, etc.. (However, do not use tags similar to the title format of

, or horizontal separation line

---

, etc., conflicts with your document your own format) and then connect some special "tags". Each marker is out of @, such as @Author or @Param, and more.

The join in the comment contains links to other files of other files (eg, your illustrations and images), you need to place those files in subdirectory named DOC-FILES. Javadoc copies these directories and files from the source directory to the document directory. Below we are classified, we may compare some tags that are commonly used.

■ General note

These tags can be used in all document comments.

◇ @since version

This tag can generate a comment indicating that this feature (class, interface, attribute, or method, etc.) is starting after which version of the software is available.

◇ @DepRecated class, attribute, method name, etc.

This tag can increase a comment, pointing out the corresponding class, method, or attribute no longer use. Javadoc only copies the first sentence to the overview section and the index. Behind the sentence can also explain why it does not encourage it. Sometimes, we also recommend another solution, for example:

@DepRecated use theanothermethod or use {@link} to mark a recommended connection About it. We will introduce it immediately.

◇ @see link

This marker adds a hyperlink in the "See Also" section. The link here can be the following items:

· Package.class # Member Label Add a link to the member's anchor link, the space in front is a hyperlink target, which is the text displayed. Note that the class and its members are # instead, you can omit the package name or even the class name is also omitted, default refers to the current package and classes, which makes the annotation more simple, but # 号 cannot be omitted. Label is omitted.

· Label This is not to explain it.

· "Text" This is directly added to the "See Also".

◇ {@LINK link target display text}

In fact, it is true that LINK's usage and SEE usage are the same. SEE is a single column in the link, while Link is directly embedded in any location in the current annotation.

■ Add comments for classes and interfaces

The annotation of the class or interface must be behind all IMPORT statements and at the same time. In addition to the conventional markers mentioned above, you can also use the following tags in class comments:

◇ @Author name

When using an Author tag, add an "Author" (Author) using the specified text text. Document comments can contain multiple @Author tags. You can specify one or more names for each @Author. Of course, you can also use multiple author tags, but they must be placed.

◇ @version version

This tag recommends a "version" entry, which can be any description of the current version.

Here is an example of a class comment:

/ **

* An Implementation of a menu bar. You add jmenu Objects to the

* Menu bar to construct a menu. When the user selects a jMenu

* Object, ITS Associated jpopupmenu is displayed, allowing the

* User to select one of the jMenuitems on it.

*

* For Information and Examples of Using Menu Bars See

*

HREF = "http://java.sun.com/docs/books/tutorial/uiswing/components/Menu.html> How to use menus ,

* a section in The java tutorial.

* For the keyboard keys buy by this component in the standard look and

* Feel (l & f) renditions, see the

* jmenubar 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

* /

■ Method Notes

Close to front of each method comment, there must be a signature of the method it described. Also except for markers of conventional uses, you can use the following annotation:

◇ @Param variable description

All parameters required by the current method need to interpret this tag, and these tags should be put together. Specific description (description) can simultaneously span multiple rows and can use HTML tags.

@Return's return value

This marker adds a return value ("Returns") section for the current method. It is also specifically described to support HTML and can cross multiple lines.

@Throws throwing the abnormality

This marker is a current method to add an entry in the "Throws" section and will automatically create a hyperlink. Specific descriptions can span multiple lines, likelirate also include an HTML tag. All throws of a method must be put together.

Here is an example of a method comment:

/ **

* Returns the model object what handles single successs.

*

* @Param ui the New MenuBarui L & f Object

* @Return the SingleselectionModel Property

* @see singleselectionModel

* @see jcomponent # getuiclassid

* @see uidefaults # getui

* /

■ Package and review annotation

The front is a comment for a certain class, method, etc., can be placed directly in the Java source file. However, in order to generate a comment, a file named package.html must be placed in the directory of each package to describe the package. The text between the label .... will be automatically extracted by JavaDoc.

You can also provide a review annotation for all source files, which is written in the overview.html file, and place it under the parent directory where all source files are located. The text between the label .... < is also automatically extracted by Javadoc, making an Overview of the document.

[How to extract the program document]

First, we still look at the basic usage of Javadoc in accordance with the practice, you can get the specific setting details of its current version through javadoc -help. Javadoc [options] [packagename] [SourceFiles] [@files]

The parameters can be arranged in any order.

· Options command line option.

· PackageNames a series of packages, space separation, must establish each package that you want to build a document. Javadoc is not recursive to each package, nor is it not allowed to use wildcard.

· SourceFiles a series of source file names, separated by spaces. Source file names can include paths and wildcards such as "*".

@Files contains one or more files of the package name and source file in any order. When you need to specify too many files in SourceFiles, you can use it to simplify the operation. The target file is a source version of the separated by space or carriage return.

The common options are:

-d path

Specifies the destination directory of Javadoc to save the generated HTML file, default is the current directory.

-AUTHOR

The author information is included in the document (will be omitted by default)

-Version

Contains version information in the document (will be omitted by default)

-Header Header text

Specifies the header file placed at the top of each output file. The header file will be placed on the right side of the upper navigation bar, and the Header text can include HTML tags and spaces, but if so, it must be enclosed with quotation marks. Any internal quotation marks in Header is not allowed to use escape.

-FOOTER FOOTER text

Specifies the footnote text placed at the bottom of each output file. The script will be placed on the right side of the lower navigation bar, others like HEADER.

-Bottom Text

Specifies the text placed at the bottom of the output file. This text will be placed on the page, located below the navigation bar. Other Tong HEADER parameters.

-Protace

Only protected and shared classes and members are displayed. This is the default.

-PUBLIC

Only public classes and members are displayed.

-package

Only display package, protected and public classes and members.

-Private

Show all classes and members, which will be very useful if it is the program document for internal development.

-SourcePath SourcePathList

When the package is passed to Javadoc, you can specify the search path of the search source file (.java). But you must note that the SourcePath option can only be used when you specify the package name with the javadoc command. If SourcePath is omitted, Javadoc uses the ClassPath to find the source file. Note: You need to set the sourcePath to the directory where the source file of the target package, for example: there is a package from C: JProject, you want to generate a document for the files inside it, then you must write C: JProjectcnComlinuxAid.

-CLATHPATH CLATHPATHLIST

Specifies the path to the Javadoc lookup "Reference Class", "Reference Class" is any class that is worthy of the document. Javadoc will search all the subdirectory of the specified path. ClassPathList can contain multiple paths that are separated by a semicolon.

Let's take an example:

Suppose we need to place the document we generated in TargetDocdir, and need to create program documentation in the c: jproject in the cn.com.linuxAid package. Then we need to enter C: JProjectCNCOM (that is, the directory containing overview.html - if you provide it). Then run javadoc -d targetdocdir cn.com.linuxAid

In addition to Javadoc provides a rich option parameter to let you customize the program document you need to generate, you can also use Doclet to generate any form of output, specific case, please read the online help documentation. Source: LinuxAid