Programing Reference For .Net,Java,C

  The Java language, the most considerate of a design is that it did not intend to allow people to write procedures written procedures - people also need to consider the issue of the documentation procedures.    The documentation of procedures, the biggest problem is the maintenance of the document.    If the documentation and code separation, then change the code after each document must change, which will undoubtedly become a very troublesome thing.    Finding a solution may seem very simple: the code with documentation "link up".    To this end, the simplest way is to be placed with all the contents of a document.    However, in order for all uniform, we must also note the use of a special kind of grammar, in order to mark a special document; It also needs a tool to extract these Notes, in accordance with the value of its demonstrated.    These are Java must be done. 
  Notes tool for extracting called javadoc.    It uses the Java compiler from some of the technology, we find the special placement procedures Notes marker.    It marked not only by those instructions from the information, will also be adjacent to the Notes category or by the method of extraction.    In this way, we can use the lightest workload generated very professional procedures document. 
  Javadoc output is a HTML document can be its own Web browser.    The tool allows us to create and manage a single source files, and generate lively useful documents.    With jvadoc, so that we can create a standard method documents.    But also because it is very convenient, we can easily obtain all the Java documents. 

  2 javadoc specific syntax all orders can only be seen in the "/**" Notes.    However, and as usual, the end of the Notes at a "*/"。    Mainly through two ways to javadoc: embedded HTML, or use "document marker."    Among them, "documents marked" (Doc tags) is the number of "@" the beginning of the orders placed in the starting line Notes (but precursor of "*" will be ignored). 
  There are three types of Notes documents, which corresponds to the Notes at the back of elements: type, variable or method.    In other words, Notes is a class definition in a class before the variables Notes right in the definition of variables before, and a method is defined in the definition of a way ahead.    If this simple example below shows: 

  / ** 1 Class Notes * / 
  (Public class docTest 
  / ** A variable Notes * / 
  Public int i; 
  / ** One way Notes * / 
  Public void f () () 
  ) 

  Javadoc only to public attention (public) and the protected (protected) members deal with the Notes document.    "Private" (private) and "friendly" (see Chapter 5) members of the Notes will be ignored, we can not see any output (also can be used - including private labeling private members).    This is justified, because the only public and protected members from the use of the document before it is the hope of customer programmers.    However, all of the Notes will contain the results, to the output. 
  The output of the code is an HTML document, and other documents with the same Java standard format.    Therefore, users will be very familiar with this format, you can be in the design category for "roaming."    Design programs, be sure to consider the importation of the above code, used to dealing with javadoc to watch the effect of the final document to HTML. 

  3 embedded HTML 
  Javadoc HTML orders will be transmitted to the final generation of HTML documents.    This will enable us to take full advantage of the enormous power of HTML.    Of course, our ultimate motive is formatted code is not to grandstand.    Below a list of examples: 

  / ** 
*
  * System.out.println (new Date ()); 
*

  * / 

  Also, as in other Web documents using HTML, as the general text formatting to make it more coherent, more beautiful: 
  / ** 
  * You can even insert a list: 
*

*
  Project 
*
  Item 2 
*
  Item 3 
*

  * / 

  Notes attention in the document, his most in the beginning of the javadoc asterisk will be discarded.    At the same time there are discarded precursor spaces.    Javadoc all content will be formatted to look and standards in line with the document.    Will not or 

  Such as embedded into HTML to use the title, because javadoc will insert the title of their own, we will be given the title with the crash. 
  Notes of all types of documents - category, variables and methods - to support embedded into HTML. 

  4 @ see: use other types of all three types of documents can contain Notes @ see Marker, which lets us use in other types of documents.    For this marker, javadoc will generate the corresponding HTML, its direct links to other documents.    Format is as follows: 

  @ See class name 
  @ See full class name 
  @ See integrity of each type of format will be automatically generated documentation, add a hyperlink "See Also" (see) entries.    Javadoc not check our attention to the designated hyperlinks, would not verify whether they are effective. 

  Five types of files embedded in HTML and accompanying marker @ see invoked category could also include documentation for the version information, as well as author's name markings.    Class documents can be used for "interface" purpose (behind the book will explain in greater detail). 

  1. @ Version 
  Format is as follows: 
  @ Version version information which "version of information" on behalf of any suitable as a version of the information.    If the command line using the javadoc "- version" markings will be generated from the HTML file from publishing this information. 

  2. @ Author 
  Format is as follows: 
  @ Author information which the author, "the author information" includes your name, e-mail address or any other appropriate information.    If the command line using the javadoc "- author" markings will be generated from specialized HTML file extract author information. 
  Can be used for a range of a number of authors such markings, but they must be continuously available.    Author information will be all together into the final HTML code in a single paragraph. 

  6 variables documents marked only variable documents including HTML, as well as embedded @ see quote. 

  7 In addition to marking methods embedded into HTML documents and @ see quoted, the method also allows for the use of parameters, return values, as well as marking the offending document. 

  1. @ Param 
  Format is as follows: 
  @ Param parameters of note, the "parameters of" refers to the list of parameters within the identifier, and the "explanation" on behalf of a number of follow-up trip can be extended to the description text.    Once encountered a new document marked on it before the end of a note.    Can be used any number of shows that each parameter one. 

  2. @ Return 
  Format is as follows: 
  @ Return note, the "note" refers to the meaning of the return value.    It can be extended to the back line. 

  3. @ Exception 
  "Offenders" (Exception) of the details of how we will be on Chapter 9.    In short, they are some special object, a method if it fails, they will be "thrown" object.    Calling a way, although there is only one target offenders, but some special method may be able to produce any number of different types of offenders.    All of these offenders need to note.    Therefore, the format of illegally labeled as follows: 
  @ Exception of the category of integrity, "complete category of" specified offences such as a name, it is in some other places defined.    And "Help" (the same can be extended to the following line) tell us why this particular type of offence will be in a method invocation. 

  4. @ Deprecated 
  This is characteristic of the new Java 1.1.    The marker to point out some of the old features have been improved over the new features replaced.    The mark is the role recommends that users do not have to use a specific kind of function, because the next revision may abandon this function.    If a marker for @ deprecated methods, the use of the method will receive compiler warning. 

Releated Articles

• Popuklar Articles