Javadoc

from Wikipedia, the free encyclopedia

Javadoc is a documentation generator , which consists of Java - source code automatically HTML created -Dokumentationsdateien. Like Java, Javadoc was developed by Sun Microsystems and is part of the Java Development Kit from version 2 .

The documentation can be enriched with special comments in the source text. Here tags are used that serve, e. B. to describe interfaces, classes, methods and fields in more detail. In addition to the standard output in HTML, alternative outputs are possible using special doclets . This is a simple form of literate programming .

functionality

When called, Javadoc receives options with information about the Java source code to be documented. Javadoc parses the source code for all Javadoc comments (starting with /**) and the following, non-local symbols. Each Javadoc comment is scanned for Javadoc tags it contains (beginning with @or {@). These contain metadata with a documentary character about the respective symbol. The existing Javadoc tag vocabulary can be expanded with the help of so-called taglets . The doclet then generates the output. The standard doclet generates output in HTML. But there are also other doclets to generate the documentation in other formats such as RTF , XML , PDF , FrameMaker , Windows Help and a few more.

Sample source code

 1 /**
 2  * Ein Hello-World-Programm in Java.
 3  * Dies ist ein Javadoc-Kommentar.
 4  *
 5  * @author John Doe
 6  * @version 1.0
 7  */
 8 public class Hello {
 9     /**
10      * Hauptprogramm.
11      *
12      * @param args Kommandozeilenparameter
13      */
14     public static void main(String[] args) {
15         System.out.println("Hallo Welt!");
16     }
17 }

Example output

An example of the output from Javadoc is the Java API documentation from Oracle (see web links ), which was created with the help of Javadoc.

Overview of the Javadoc tags

Day and parameters output Use in since
@author Surname Describes the author. Class, interface
@version version Creates a version entry. A maximum of once per class or interface. Class, interface
@since jdk version Since when the functionality has existed. Class, interface, instance variable, method
@see reference Creates a link to another element of the documentation. Class, interface, instance variable, method
@serial Describes the serialized data of an Serializableobject. class
@serialField Documents a field of an Serializableobject. Class, method
@param name description Parameter description of a method. method
@return description Description of the return value of a method. method
@exceptionclassname description
@throwsclassname description		 Description of an exception that can be thrown by this method. method
@deprecated description Describes an obsolete method that should no longer be used. Should always be used with the @Deprecatedannotation as of Java 5.0 . method
{@inheritDoc} Copies the description from the overwritten method. Overriding method 1.4.0
{@link reference} Link to another symbol. Class, interface, instance variable, method
{@linkPlain reference} The link is displayed in standard text instead of the source text character set. Class, interface, instance variable, method 1.4.0
{@value} Returns the value of a constant field. Static field 1.4.0
{@docRoot} Returns the absolute path to the main directory. Package, classes, fields, methods
{@code} Formats text to the letter with the source text character set (corresponding to <code> ) and suppresses the interpretation of the HTML or Javadoc tags it contains. Class, interface, instance variable, method 5.0
{@literal} Identifies text that is true to the letter and suppresses the interpretation of the HTML or Javadoc tags it contains. Class, interface, instance variable, method 5.0

To use the symbol " @" without starting a Javadoc tag, the HTML character code " &#064;" can be used. This is useful, for example, in a code example within a Javadoc comment to use annotations that @start with a " " like a Javadoc tag .

Similar tools

Web links