Documentation Tool - Msadaf/Cse327.6T2 GitHub Wiki

There are two types of documentation tool mentioned. A brief description is given with the tool names.

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[3] used by Javadoc is the de facto industry standard for documenting Java classes.Javadoc also provides an API for creating doclets and taglets, which allows users to analyze the structure of a Java application.

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 /**.

  1. The first paragraph is a description of the method documented.
  2. 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)

Some Javadoc tags

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

  • @author-Describes an author. Used in Class, Interface, Enum
  • {@docRoot} -Represents the relative path to the generated document's root directory from any generated page.Used in Class, Interface, Enum, Field, Method
  • @version version-Provides software version entry. Max one per Class or Interface.Used inClass, Interface, Enum
  • @since since-text-Describes when this functionality has first existed.Used in Class, Interface, Enum, Field, Method
  • @see reference-Provides a link to other element of documentation.Used in Class, Interface, Enum, Field, Method
  • @param name description -Describes a method parameter.Used in Method
  • @return description -Describes the return value.Used in Method
  • @exception classname description-Describes an exception that may be thrown from this method.Used in Method
  • @throws classname description-Describes an exception that may be thrown from this method.Used in Method
  • @deprecated description- Describes an outdated method.Used in Class, Interface, Enum, Field, Method
  • {@inheritDoc} -Copies the description from the overridden method.Used in Overriding Method
  • {@link reference} -Link to other symbol.Used in Class, Interface, Enum, Field, Method
  • {@linkplain reference} -Identical to {@link}, except the link's label is displayed in plain text than code font.Used in Class, Interface, Enum, Field, Method
  • {@value #STATIC_FIELD} -Return the value of a static field.Used in Static Field
  • {@code literal} -Formats literal text in the code font. It is equivalent to {@literal}.Used in Class, Interface, Enum, Field, Method

References:

https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html

https://en.wikipedia.org/wiki/Javadoc

⚠️ **GitHub.com Fallback** ⚠️