Javadoc Guidelines - RohanNagar/thunder GitHub Wiki

When writing Javadoc within the Thunder project, developers should be adding Javadoc documentation to classes and methods. The following guidelines should be followed when writing or modifying Javadoc.

These Javadoc guidelines are based off of the Liferay Javadoc guidelines.

1. Class Javadoc Overview
2. Class Descriptions
3. Class Javadoc Tags
4. Method Javadoc Overview
5. Method Descriptions
6. Method Javadoc Tags
7. Javadoc Linking
8. Formatting Tags

The following items are required for class-level Javadoc.

1. A description that describes the purpose of the class. See class descriptions below for more information.

   Checked by JavadocType, JavadocStyle, and SummaryJavadoc Checkstyle rules.

2. @param tags. Only necessary if the class has a generic type parameter.

   Checked by JavadocType and NonEmptyAtclauseDescription Checkstyle rules.

3. @see tags. Only necessary if related classes would help the reader get a clearer view of the purpose of the class. This usually includes a parent class, any important ancestors, and the primary classes that use this class.

   Not checked by Checkstyle rules.

4. @since/@deprecated tags. @since is only necessary if the class has moved packages or is replacing another class. @deprecated is only necessary if the class is deprecated for later removal.

   Not checked by Checkstyle rules.

The following are rules for class descriptions:

• Start with a verb - You should almost always start a class description with a verb to describe the purpose of the class.

  Example (UserResource):

  /**
   * Provides API methods to create, fetch, update, and delete {@code User}
   * (in the {@code api} module) objects. The methods contained in this class are
   * available at the {@code /users} endpoint, and return JSON in the response.
   */

  Not checked by Checkstyle rules.

• Never begin with This class - Never begin the description with This class or anything similar. However, it is acceptable to use this wording in later sentences/paragraphs.

  Checked by SummaryJavadoc Checkstyle rule.

• For an interface and its class - If some explanation is necessary to distinguish an interface from its class, follow the format below (e.g. UsersDao.java):

  Provides the base interface for the UsersDao service. Provides methods to create,
  update, get, and delete users from a database.
  

  Likewise, the description of the implementation could be as follows (e.g. DynamoDbUsersDao.java):

  Provides the DynamoDB implementation for the UsersDao service. Provides methods to create,
  update, get, and delete users from a database.
  

  Not checked by Checkstyle rules.

• For model classes (API entities) - describe the methods and entities represented in the class. Use the following format:

  Represents a user, providing access to the user's email, password, and additional properties.
  

  In the above example:

  • State what entity the class represents (Represents a user,)
  • Describe what the entity provides (providing access to the user's properties).

  Not checked by Checkstyle rules.

Use @param tags for a class or interface's generic type parameters. This should be the only case where a class/interface has parameters to document.

The parameter type name should keep its syntax when defined. For example, this interface:

public interface BinaryFunction<T> extends Function<T, BinaryFile> {

should define the generic type parameter like this:

@param <T> the model's type

Checked by JavadocType and NonEmptyAtclauseDescription Checkstyle rules.

Use @see tags to link other closely related classes whose Javadocs would give the reader a clearer picture of the purpose of the class. This can include a parent class, any important ancestors, and the primary classes that use this class. An example of an @see tag declaration is the following:

@see com.sanctionco.thunder.authentication.ThunderAuthenticator ThunderAuthenticator

Not checked by Checkstyle rules.

The @since tag should always be used in cases where the class replaces a deprecated class or where the class has been moved to a new package. Deprecation due to moving a class or replacing a class necessitate respective use of a @deprecated tag in the old class and a @since tag in the new class. For specifying the version, use the next major version that has yet to be released.

The preferred format for common @since messages are listed below.

Not checked by Checkstyle rules.

The @deprecated tag should provide a short description that includes the version of initial deprecation, why the class was deprecated, and a link to what should be used in its place. For specifying the version, use the next major version that has yet to be released.

Note, if a class deprecation was due to moving or replacing a class, then the comments for the new class should include an @since tag referencing the old class. See the former section for details.

The preferred format for common @deprecated messages are listed below.

Not checked by Checkstyle rules.

Method-level Javadoc should be written for all methods that are not simple getters/setters.

Do not write method Javadocs for simple getters/setters. However, if the getter/setter is more involved than a single line, then you should write a Javadoc for that method.

Checked by JavadocMethod#minLineCount Checkstyle rule.

Do not write method Javadocs for @Override methods, especially equals(), hashCode(), and toString() Only write Javadocs for @Override methods if you have additional documentation to add. In that case, start the Javadoc with {@inheritDoc}.

Checked by JavadocMethod#allowedAnnotations Checkstyle rule.

The following items are required for method-level Javadoc.

1. A description that describes the purpose of the method. See method descriptions below for more information.

   Checked by JavadocMethod, JavadocStyle, and SummaryJavadoc Checkstyle rules.

2. @param tags for all method parameters.

   Checked by JavadocMethod and NonEmptyAtclauseDescription Checkstyle rules.

3. @return tag that describes what the method returns.

   Checked by JavadocMethod and NonEmptyAtclauseDescription Checkstyle rules.

4. @throws tag that describes all of the exceptions that the method may throw.

   Checked by JavadocMethod and NonEmptyAtclauseDescription Checkstyle rules.

5. @see tags. Only use @see when there are more details about something that could be gained by reading the docs for another method or class.

   Not checked by Checkstyle rules.

6. @since/@deprecated tags. @since is only necessary if the method is replacing another or is renamed. @deprecated is only necessary if the method is deprecated for later removal.

   Not checked by Checkstyle rules.

Method descriptions should be split into two parts: the first sentence of the description, and the rest of the description. The first sentence (short description) is what most people will read and should be the most informative.

Always use a verb to describe the method. The preferred format for the initial descriptions of several common methods are listed below.

There are a few general rules for method descriptions:

1. When referring to the current instance, say "this something".

   Example: Returns <code>true</code> if this person is an administrator.

   Not checked by Checkstyle rules.

2. When referring to parameters, use "the" instead of "a".

   Example: Returns the localized preferences value for the key.

   Not checked by Checkstyle rules.

3. If there are multiple overloaded methods of the same name, each method should have a complete description of itself. Do not @see the other overloaded forms.

   Distinguish between overloaded methods by uniquely describing each method in the first sentence of the method description. This helps developers spot out which of the overloaded methods they want to use when viewing the Javadoc summary of the methods for the class. Remember, only the first sentence of the method description shows in the method summary. The remaining sentences (including sentences of the same paragraph following the first sentence) are available in the full length method description.

   /**
    * Determines if the user object is valid. Checks to ensure that the user is not null,
    * the user's email is not null, the email address is valid, and that the user has a valid
    * property map.
    * ...
    */
   public void validate(User user)

   and

   /**
    * Determines if the given password and email are valid. Checks to ensure both are not null
    * or empty.
    * ...
    */
   public void validate(String password, String email)

   Not checked by Checkstyle rules.

4. Start the description with Returns ... for a method used primarily for the value it returns.

   /**
    * Returns HTML to display as a success page after user verification.
    * ...
    */
   public Response getSuccessHtml()

   Not checked by Checkstyle rules.

5. Avoid simply restating the name of the method in the description. If it is not immediately obvious what a method does, it needs more explanation.

   For example, the following is NOT a good example of a method description:

   /**
    * Updates the localization.
    */
   public String updateLocalization(String xml, String key, String value, String requestedLanguageId);

   Write the following instead:

   /**
    * Updates the localized string for the language in the localizations XML.
    */
   public String updateLocalization(String xml, String key, String value, String requestedLanguageId);

   Not checked by Checkstyle rules.

Unless the details describing a method warrant a paragraph, simply add the sentence(s) directly after the initial method description.

/**
 * Verifies the given email, marking it as verified in the database if the token matches the
 * stored verification token. Depending on the given response type, the method will either return
 * a response that contains the updated verified user or will redirect to an HTML success page.
 */

Important: In the HTML generated from the Javadoc, only the initial method description sentence will appear in the method summary table. But the sentences that follow the initial method description will show in the method details.

@param tags should provide a short description of what the parameter is or what it is for, as well as any special requirements. If more detail is needed than what can fit in one or two sentences, place it in the method description instead. Never start the parameter description with a capital letter, and always refer to the parameter with "the" rather than "a". Additionally, it is unnecessary to explain what the parameter is for if this was already explained in the method description.

The preferred format of several common parameter types are shown below. Be sure to include the description text found in bold.

Bad example:

/**
 * Returns the name of the role.
 *
 * @param roleId the primary key of the role **whose name to get**
 * @return the name of the role
 */
String getRoleName(long roleId)

Good example:

/**
 * Returns the name of the role.
 *
 * @param roleId the primary key of the role
 * @return the name of the role
 */
String getRoleName(long roleId)

Sometimes, a parameter description may require more than one phrase. Any additional content following the initial parameter phrase description must be written in complete sentences, followed by a period. For example:

@param  trusted whether to bypass permission checks. In third-party
        repositories, this parameter may be ignored.

To show possession, use an apostrophe rather that ending a sentence with a preposition. The only exception is that when referring to a primary key, always write "the primary key of the user", not "the user's primary key". Example:

/**
 * @param  creatorUserId the primary key of the user's creator
 * @param  companyId the primary key of the user's company
 * @param  name the user's name
...
 * @param  groupIds the primary keys of the user's groups
 */
public User addUser(long creatorUserId, long companyId, name, ... , long[] groupIds, ...)

The @return tag should provide a short description of what the method returns, including any special values. If a method returns null, this should be explicitly stated. Otherwise, the reader should assume the method will always return its designated type.

As a rule of thumb, describe the return value in simple terms. Leave to method and parameter descriptions details on what can cause subtle variations in values returned.

The preferred format for the return descriptions of several common method types are shown below.

Note using the word "the" (not "a" or "an") in describing the returned item.

If a method uses more than two criteria items to match an entity or is awkward to consolidate into a small sentence, just use the phrase "the matching somethings" to start of the description of the returned entities.

/**
 * Returns an ordered range of all the file entries in the group starting at
 * the root folder that are stored within the Liferay repository.
 * ...
 * @return the range of matching file entries ordered by the comparator
 * ...
 */

Only include a message about the side effects of a parameter in the @return description if the parameter can have a side effect apart from the main purpose of the method. For instance, if the primary purpose of a parameter was to tell the method to use an alternate data source, but a failure in using the alternative data source caused the method to return null rather than throw an exception, say in the @param the parameter can change the data source, and then say in the @return that a failure in using the alternative data source could cause null to be returned, and say in the @throws the exception wouldn't be thrown under this circumstance.

@throws should give a short description of when an exception will be thrown. They should always be written in the past tense.

If you know what could cause an exception, briefly describe the circumstances. For example:

@throws DatabaseException if a user with the primary key could not be found

If it is difficult to describe exactly what will cause certain exceptions to be thrown, use the following generic description:

@throws RuntimeException if a runtime exception occurred

If you describe what could cause an exception, but cannot provide an exhaustive list of all of the possible causes, end your comment generalizing that the type of exception could have occurred. For example:

@throws DatabaseException if a user with the primary key could not be
        found, if the password was incorrect, or if a database exception
        occurred

• Key Not Found

  Pattern: if a <entity1> [or entity2] with the primary key could not be found

• Invalid Information

  Pattern: if the <entity's> information was invalid

• Start New Reasons with if: Start each new type of reason for the exception with the word if.

  Pattern: @throws PortalException if <reason type1> or if <reason type2>

/**
 * ...
 * @throws PortalException if a creator or parent organization with the
 * primary key could not be found or if the organization's information was
 * invalid
 * ...
 */
public Organization addOrganization(long userId, long parentOrganizationId, … , ServiceContext serviceContext)
throws PortalException, ...

Only use @see when there are more details about something that could be gained by reading the docs for another method or class. An example of an @see tag declaration is the following:

@see com.sanctionco.thunder.dao.UsersDao#findByEmail()

The @since tag should be used in cases where the method is a result of renaming a former method.

Note, deprecations due to renaming a method should include both the use of @deprecated in the old method and @since in the new method.

The preferred format for common @since messages are listed below.

The @deprecated tag should provide a short description that includes the release/version of initial deprecation, why the method was deprecated, and a link to what should be used in its place.

Note, if a method deprecation was due to moving or replacing a method, then the comments for new method should include an @since tag referencing the old method. See the previous section for details.

The preferred format for several common @deprecated messages are listed below.

Most Javadoc errors result from the incorrect usage of the @see and @link tags. Make sure to follow the following rules when using links in your Javadocs:

• @see tags should only be used directly below the class/method description, not within.

• @link tags should be used within descriptions, and surrounded by {} (e.g., {@link DDMStructureServiceImpl}.

• You MUST specify the class' full package path if the class you're referencing is not located in the same package as the class you're documenting.

• Do not include full package paths unless it is necessary.

• You can link to an external URL by using the <a> HTML tag and href attribute. You should not use this linking method with any other Javadoc tags (e.g., @link or @see).

• @link examples:

  Within same class:

  {@link #updateStructure(long, long)}
  

  Diff class, same package:

  {@link DDMStructureLocalServiceImpl#updateStructure(long, long)}
  

  Diff package:

  {@link com.liferay.portlet.dynamicdatamapping.service.impl.DDMStructureLocalServiceImpl#updateStructure(long, long)}
  

  Field example:

  {@link com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS}
  

Important: You cannot link to classes/methods that reside outside of a particular module. For instance, api and application are separate JARs, so classes/methods in these JARs can not link to each other. The same rule goes for all modules; since each module is a separate JAR, linking cannot be done outside a particular module. Because of the inability to successfully link to other areas of Thunder's source code, you must specify where the referenced code is located, and rely on readers to manually find it.

In some cases, there are many different methods in a class with the same name and different parameters. If this is the case, specify the parameters when referencing the method. If the method name in the class is unique, there is no need to list the method's parameters.

Below are examples of how to specify code outside the current class's area.

Suppose you want to specify the User class located in the com.sanctionco.thunder.models module from another class outside the current module. You would specify it as the following:

See {@code User} in the {@code api} module

To specify a method in another module:

See {@code User#getEmail} in the {@code api} module

If you'd like to specify a class in another module mid-sentence, you could refer to it like this:

{@code User} (in the {@code api} module)

Since deprecations typically use links to refer to replaced code, this format for code outside the area is applied for @deprecated tags, as well:

@deprecated As of 7.1.0, replaced by {@code UsersDao#delete(String, boolean)} in the {@code application} module

Notice that the @see and @link tag are never used. Configuring a link for a class/method that cannot be found results in a Javadoc error during compilation; therefore, refrain from using "linking" tags in these scenarios.

• All HTML tags (except for <b>, <i>, <code>, etc.) should be on a line by themselves.
  • Note: When using table tags, you must insert a line return between <table> and the start of the content nested within. The same rule also applies before the ending </table> tag.
  • For an example of using list tags, both ordered and unordered, see the class comment example below.
• Unordered and ordered lists in comments should be represented using <ul> or <ol> respectively. The <ul> and </ul> or <ol> and </ol> tags should each be on a line of their own. List items should each be placed on their own line, and the <li> and </li> tags should be on their own line immediately before and after the item text.
• Unordered and ordered lists must not be nested within paragraph (<p>``</p>) tags.
• Tables (<table>...</table>) must be nested within paragraph (<p>``</p>) tags.
• Pre-formatted text (<pre>...</pre>) must be nested within paragraph (<p>``</p>) tags.
• Multi-line code blocks (see below bullet) must be nested within pre-format tags (<pre>``</pre>).
• Format all keywords, special constants (true, false, null), and file names (config.yaml) as code using the Javadoc @code tag (e.g., {@code true})
• With regards to class constants, be sure to reference their class either by including the full path of the constant (e.g., {@link com.sanctionco.thunder.authentication#TYPE_ASSET}) or wrapping the constant(s) in @code tags followed by a reference to the class with its full path.
  • For example, {@code TYPE_ASSET} and {@code TYPE_CREATOR} defined in {@link com.sanctionco.thunder.authentication.ThunderAuthenticator}.

Formatting tags example:

/**
 * Represents an example class. If a basic description requires more than one
 * sentence, include it in the first paragraph.
 *
 * <p>
 * Example of a second paragraph. Note the blank line between the first <p> tag
 * and the end of the first paragraph.
 * </p>
 *
 * <ul>
 * <li>
 * Example list, item 1
 * </li>
 * <li>
 * Item two
 * </li>
 * </ul>
 *
 * <p>
 * Another paragraph with more information in it. Example code should be placed
 * inside <pre><code> tags, as shown below.
 * </p>
 *
 * <p>
 * <pre>
 * <code>
 * Example myExample = new Example();
 * </code>
 * </pre>
 * </p>
 *
 * <p>
 * Notice the Javadoc tag values are lined up.
 * </p>
 *
 * <p>
 * Here is a table example:
 * </p>
 *
 * <p>
 * <table>
 * <tr>
 * <th>
 * Column Header 1
 * </th>
 * <th>
 * Column Header 2
 * </th>
 * <th>
 * Column Header 3
 * </th>
 * </tr>
 * <tr>
 * <td>
 * Data 1
 * </td>
 * <td>
 * Data 2
 * </td>
 * <td>
 * Data 3
 * </td>
 * </tr>
 * </table>
 * </p>
 *
 * @see	   BigExample
 */
public class Example {
	...
}