Javadoc
Javadoc automatically creates docs from javadoc comments in your code.
Javadoc comments are multi-line comments that start with /**, instead of /*. You can write HTML, text and tags in them.
Generating Javadocs
Generating javadocs is done with the javadoc command:
$ javadoc -d ./docs source.java
This will make a static page with source ./docs.
Tags
The following tags are available as sourced from: wikipedia.org/wiki/Javadoc.
The tags used in this lecture are highlighted in bold.
| Tag & Parameter | Usage | Applies to | Since |
|---|---|---|---|
| @author John Smith | Describes an author. | Class, Interface, Enum | |
| {@docRoot} | Represents the relative path to the generated document’s root directory from any generated page. | Class, Interface, Enum, Field, Method | |
| @version version | Provides software version entry. Max one per Class or Interface. | Class, Interface, Enum | |
| @since since-text | Describes when this functionality has first existed. | Class, Interface, Enum, Field, Method | |
| @see reference | Provides a link to other element of documentation. | Class, Interface, Enum, Field, Method | |
| @param name description | Describes a method parameter. | Method | |
| @return description | Describes the return value. | Method | |
| @exception classname description / @throws classname description | Describes an exception that may be thrown from this method. | Method | |
| @deprecated description | Describes an outdated method. | Class, Interface, Enum, Field, Method | |
| {@inheritDoc} | Copies the description from the overridden method. | Overriding Method | 1.4.0 |
| {@link reference} | Link to other symbol. | Class, Interface, Enum, Field, Method | |
| {@linkplain reference} | Identical to {@link}, except the link’s label is displayed in plain text than code font. | Class, Interface, Enum, Field, Method | |
| {@value #STATIC_FIELD} | Return the value of a static field. | Static Field | 1.4.0 |
| {@code literal} | Formats literal text in the code font. It is equivalent to {@literal}. |
Class, Interface, Enum, Field, Method | 1.5.0 |
| {@literal literal} | Denotes literal text. The enclosed text is interpreted as not containing HTML markup or nested javadoc tags. | Class, Interface, Enum, Field, Method | 1.5.0 |
| {@serial literal} | Used in the doc comment for a default serializable field. | Field | |
| {@serialData literal} | Documents the data written by the writeObject( ) or writeExternal( ) methods. | Field, Method | |
| {@serialField literal} | Documents an ObjectStreamField component. | Field |