1. Development backgroundI have been writing the Dubbo interface recently, always writing interface descriptions with Word documents and then sending them to others. Now there are too many, and people who are connected with others in a hurry to use, there is no time to write Word documents. Then think about how to use Doc document annotations to automatically generate the interface documentation. Originally a bit of an impression on this piece, but not familiar with, plus no very strong intention to use, so has not been. Today to thank the company's great God, everyone called him the European God, God-like man. Let me use the document comment. Then we know how to do it, and the following is the process of generating it.2. Generation MethodLet's start with the method of generation, so that the annotation specification may seem tedious to the reader at first, and the annotation specification basically has its own approach. As long as the annotations are normalized, it is easy to generate a comment document. 2.1 Click Project->generate Javadoc The following interface appears Javadoc command: Executes the doc document comment commands, or you can enter this command in the CMD window select type s for which Javadoc'll be generated: the project where you want to generate a document comment, select the Dubbo intermediate price item, where the interface is declared, and the resulting document is natural enough. Create Javadov for menbers with Cisi Bility: The private attribute is also generated to the document, the default is public, the privatedestination: Generate document Path 2.2 Click the next page configuration basically all choose the default, Can also be based on their own urine to check the necessary things here can also import their own style files, which can make the document more beautiful, here omit 2.3 Click the next step here to enter the definition of a custom @ tag, as follows:-encoding UTF-8-charset UTF-8-tag function description \: : A: "Function description"-tag project name \::a: "Project name"-tag Project version \::a: "Project version"-tag Create author \::a: "Create author"-tag Creation date \::a: "Creation date"-tag Question feedback \::a: "Problem feedback" of course, You don't have to enter anything if you all use Doc's label. 2.4 Click Finish and then go to the doc path generated in the 2.1 step to open index.html can see the doc document, the results are as follows: to get here to complete the steps of the generation, the following I say a little bit of notes to note, for the annotation specification of the people can not look down, But if there is basically nothing in the API that you generate, it is recommended that you look at the content below.3.doc Comments3.1 Multiline comments for properties, methods, comments for the class must use a multiline comment, and a single-line comment will not be generated into the document 3.2 property Comment:/** employee ID */private String workerid; 3.3 method Comment:/*** @ function Description: <p> according to Workerid search brokers Community band See List </p>* <p><font color=red> Note: </font>* only return according to the band to see the quantity, Last time reverse sort of the previous topnum record </p>* @ created by: * * Created: September 22, 2016 PM 3:11:46* @param workerid Employees id* @param topnum sort the first few * @ret Urn <p> return object reference {@link bigdataresult}<{@link list}<{@link agentdkrecordvo}>></p>*/public Bigdataresult<list<agentdkrecordvo>> queryagentdklist (String workerid, Integer topnum); Here the use of annotations to generate beautiful documents, parameters and return objects must be written clearly, if there are object parameters, you can use @see annotations, examples are as follows:/*** @ Function Description: According to Workerid check broker transaction record * @ Create Author: * * * Date Created: September 22, 2016 PM 8:49:02* @param workerid Employee id* @param page Page Object * @return <p> return object reference {@link bigdataresult}<{@link List }<{@link esfcjhqhouseinfo}>></p>* @see pageinfo*/public bigdataresult<list<esfcjhqhouseinfo >> Queryesfcjlistbyworkerid (String workerid, PageInfo page); the @see and @link here can be linked to the annotated document page of the specified object, with a specific difference in use once.However, at the same time @see and @link objects are also required to guide the package, the use of the global qualified name, such as @see java.util.List of course, you can also add some of their own definitions of annotations, these annotations to be generated in the document comments in the 2.3 steps as stated, such as @ Function description 3.4 class Comment/*** @ Function Description: interface return error code * @ Project version: 1.0.0* @ project name: Big Data Interface Center * @ Relative path: *. resultcodecenter.java* @ Create Author: * * @ Problem Feedback: **@126.com* @ created: September 22, 2016 PM 2:32:53*/public class Resultcodeconstant {}& nbsp4 Comment TemplateClick Window->preferences, the Search box to enter "template", you can see the templates set options, for a chestnut: here can be the properties, methods, classes, and more content to do template settings, so input comments when the Can be unified, and without the pain of multiple typing, is a class of annotation template with these basically generated interface documentation is enough, of course. If there are higher requirements or comments have their own specifications, you can also set more content according to their own. For informational purposes only, please forgive me for your shortcomings. Reprint please indicate the source. If you have any questions, please feel free to comment or contact my email[email protected]
Comment Generation API documentation
