• Source: Javadoc

Javadoc is a documentation generator created by Sun Microsystems for the Java language (now owned by Oracle Corporation) for generating API documentation in HTML format from Java source code. The HTML format is used for adding the convenience of being able to hyperlink related documents together.
The "doc comments" format used by Javadoc is the de facto industry standard for documenting Java classes. Some IDEs, like IntelliJ IDEA, NetBeans and Eclipse, automatically generate Javadoc templates. Many file editors assist the user in producing Javadoc source and use the Javadoc info as internal references for the programmer.
Javadoc also provides an API for creating doclets and taglets, which allows users to analyze the structure of a Java application. This is how JDiff can generate reports of what changed between two versions of an API.
Javadoc does not affect performance in Java as all comments are removed at compilation time. Writing comments and Javadoc is for better understanding the code and thus better maintaining it.




History


Javadoc was an early Java language documentation generator. Prior to the use of documentation generators it was customary to use technical writers who would typically write only standalone documentation for the software, but it was much harder to keep this documentation in sync with the software itself.
Javadoc has been used by Java since the first release, and is usually updated upon every new release of the Java Development Kit.
The @field syntax of Javadoc has been emulated by documentation systems for other languages, including the cross-language Doxygen, the JSDoc system for JavaScript, EDoc for Erlang, and Apple's HeaderDoc.




Technical architecture






= Structure of a Javadoc comment

=
A Javadoc comment is set off from code by standard multi-line comment tags /* and */. The opening tag (called begin-comment delimiter), has an extra asterisk, as in /**.

The first paragraph is a description of the method documented.
Following the description are a varying number of descriptive tags, signifying:
The parameters of the method (@param)
What the method returns (@return)
Any exceptions the method may throw (@throws)
Other less-common tags such as @see (a "see also" tag)




= Overview of Javadoc

=
Most Javadoc comments are imbedded inside
/** ... */ tags. The Javadoc comment block is positioned immediately above the items
without any separating newline, and below any import statements.The class declaration usually
contains:

Documentation comments for methods usually contain a short, concise, one line description to
explain what the item does, followed by a longer description, and lastly a tag section that lists accepted input arguments and return values of the method. The
Javadoc is treated as HTML, so a "

" paragraph break tag can be used to denote multiple paragraphs.

Variables are documented similarly to methods, but often lack the tags at the end of the comment.

It is not recommended to define multiple variables in a single documentation comment, as Javadoc reads each variable and places them separately to the generated HTML page with the same documentation comment that is copied for all fields.

Instead, it is recommended to write and document each variable separately:




= Table of Javadoc tags

=

Some of the available Javadoc tags are listed in the table below:




= Examples

=
An example of Javadoc to document a method follows. Notice that spacing and number of characters in this example are as conventions state.




Doclets


Doclet programs work with the Javadoc tool to generate documentation from code written in Java.
Doclets are written in the Java programming language and use the Doclet API to:

Select which content to include in the documentation
Format the presentation of the content
Create the file that contains the documentation
The StandardDoclet[1] included with Javadoc generates API documentation as frame-based HTML files. Many non-standard doclets are available on the web , often for free. These can be used to:

Create other non-API types of documentation
Output the documentation to other non-HTML file types such as PDF
Output the documentation as HTML with additional features such as a search or with embedded UML diagrams generated from the Java classes




See also


Comparison of documentation generators
.NET XML documentation comments




References






External links


Java Platform, Standard Edition Javadoc Guide
JSR 260 Javadoc Tag Technology Update Java Specification Request (defines new Javadoc tags)
Improve on Javadoc with ashkelon
Various Java documentations converted to Windows Help format

Kata Kunci Pencarian:

• Java
• Javadoc
• Jenkins (software)
• Java (programming language)
• PHPDoc
• JDiff
• Natural Docs
• ReStructuredText
• Documentation generator
• ROBODoc
• Java annotation