Automatically generate your program development documentation

Http://linuxaid.com.cn

01-12-21 11:52 3850P

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 its own code style. If you want to analyze translation, it is prone to machine code is more prone to generate a hundred times. 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 The following tags can be used in all document comments. ◇ @since version This tag can generate an annotation indicating that this feature (class, interface, attribute, or method, etc.) are starting after which version is available. @DepRecated class, attribute, method name, etc. 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, such as @Deprecated use theanothermethod or use {@link} to give a recommended connection About it. We will introduce it. @See link This tag adds a hyperlink in the "See Also" section. The link here can be the following item: · Package.class # MEMBER Label Add a link to the member's anchor link, the space in front is the 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 the LINK usage and SEE usage are the same, and see is single column in the link, while link is in any position in the current comment directly embed a band super Link text. ■ Adding a comment class for class and interface The annotation of the interface must be behind all IMPORT statements, while it is also in front of the Class definition. In addition to the conventional tags mentioned above, you can also use the following tags in class annotations: ◇ @Author Author Name When using the Author tag, add the "Author" item in the generated document with 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, the back text can be any description of the current version.

Here is an example of class comments: / ** * An Implementation of a menu bar. You add jMenu Objects to the * menu bar to construct a menu .hen the user selects a JMenu < / code> * Object, ITS Associated jpopupmenu is displayed, allowing the * user to select one of the jMenuitems on it. *

* for information and example of using Menu Bars See * How to use menus , * a section in The Java Tutorial. * for the keyboard keys Used by this Component In The Standard Look and * Feel (L & f) Renditions, See the * 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 RELESE 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 Note Close to front of each method comment, there must be a signature of the method it described. Also except for the use of routine uses, you can use the following annotation: ◇ @Param variable describes all the parameters required by the current method, you need to use this tag to explain, and these tags should be put together. Specific description (description) can simultaneously span multiple rows and can use HTML tags. @Return's return value of this method This tag is the current method to add a return value ("returns") section.

It is also specifically described to support HTML and can cross multiple lines. @Throws This method throwing an exception This tag is the current method Add an entry in the "THROWS" section and automatically creates a hyperlink. Specific descriptions can span multiple lines, likelirate also include an HTML tag. All throws of a method must be put together. The following is an example of a method NOTE: / ** * Returns the model object that handles single selections * * @param ui the new MenuBarUI L & F object * @return the SingleSelectionModel property * @see SingleSelectionModel * @. See jComponent # getuiclassid * @see uidefaults # getui * / ■ Package and Summary Note The front of the comment is 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 the Overview of the document [How to extract the program document] First, we still take a look at the basic usage of Javadoc in accordance with the practice, you You can get the specific setting details of its current version through javadoc -help. Javadoc [options] [packagefiles] [@files] 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 options commonly used include: -d path Specifies the destination directory of Javadoc to save the generated HTML file, default is the current directory. -Author includes author information in the document (by default) -Version contains version information in the document (which is omitted by default) -Header Header text specifies the header file on 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.