Javadoc Guidelines

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.

Class Javadoc

The following items are required for class-level Javadoc.

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

Checked by JavadocType, JavadocStyle, and SummaryJavadoc Checkstyle rules.
@param tags. Only necessary if the class has a generic type parameter.

Checked by JavadocType and NonEmptyAtclauseDescription Checkstyle rules.
@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.
@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.

Class Descriptions

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

#f03c15 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.

Class Javadoc Tags

@param tags

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

#c5f015 Checked by JavadocType and NonEmptyAtclauseDescription Checkstyle rules.

@see tags

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

#f03c15 Not checked by Checkstyle rules.

@since tags

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.

Reason	@since Description
Replaced an existing class	@since version, replaced {@link fully qualified class}
Moved to different package	@since version, moved from {@link fully qualified class}

#f03c15 Not checked by Checkstyle rules.

@deprecated tags

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.

Deprecation Reason	@deprecated Description
Replaced	As of version, replaced by {@link fully qualified class}
Moved to different package	As of version, moved to {@link fully qualified class}
Some other reason	As of version, because of some reason
Not replaced	As of version, with no direct replacement

#f03c15 Not checked by Checkstyle rules.

Method Javadoc

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.

#c5f015 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}.

#c5f015 Checked by JavadocMethod#allowedAnnotations Checkstyle rule.

The following items are required for method-level Javadoc.

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

Checked by JavadocMethod, JavadocStyle, and SummaryJavadoc Checkstyle rules.
@param tags for all method parameters.

Checked by JavadocMethod and NonEmptyAtclauseDescription Checkstyle rules.
@return tag that describes what the method returns.

Checked by JavadocMethod and NonEmptyAtclauseDescription Checkstyle rules.
@throws tag that describes all of the exceptions that the method may throw.

Checked by JavadocMethod and NonEmptyAtclauseDescription Checkstyle rules.
@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.
@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

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.

Short Description Sentence

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

Method Type	Description
constructor(value)	Constructs a new ... with the given value.
getSomething()	Returns the something of this thing.
getSomethings()	Returns the somethings of this thing. (Note, do not refer to collection type; instead, refer to the something in plural form.)
isSomething()	Returns {@code true} if this thing is something.
deleteSomething()	Deletes the something.
provideSomething()	Provides an instance of something.
updateSomething(value)	Updates the something with the new value.

There are a few general rules for method descriptions:

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.
When referring to parameters, use "the" instead of "a".

Example: Returns the localized preferences value for the key.

Not checked by Checkstyle rules.
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.

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()

#f03c15 Not checked by Checkstyle rules.

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);

#f03c15 Not checked by Checkstyle rules.

Longer Descriptions

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.

Method Javadoc Tags

@param tags

@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.

Param case	Param name convention	@param Description
An entity's ID	entity ID	the primary key of the entity
An entity's attribute or field	paramName	the entity's attribute
An involved entity (possibly the method's subject)	classname (lowercase)	the (refer to the entity in layman's terms in lower case. Do not refer to the uppercase classname.)
A boolean parameter	paramName	whether to do something or some condition is true

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, ...)

@return tags

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.

Method Type	@return Description
getSomething()	the something of this thing
getSomethings()	the somethings of this thing (Note, do not refer to the collection type; instead, refer to the something in plural form)
changeSomething(thing)	the changed thing, or {@code null} if the change failed
isSomething()	{@code true} if something; {@code false} otherwise

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

Abbreviating return description when extensive matching done

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

Parameter Side Effects

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 tags

@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, ...

@see tags for methods

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()

@since tags for methods

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.

Reason	@since Description
Renamed a former method	@since version, rename of {@link #someMethod()}
Generalization	@since version, replaced {@link #someMethod()}

@deprecated tags for methods

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.

Deprecation Reason	@deprecated Description
Replaced	As of version, replaced by {@link fully qualified path or #method name}
Renamed within same class	As of version, renamed to {@link #someMethod()}
Generalized in another method within same class	As of version, replaced by the more general {@link #someMethod()}
Moved to different package	As of version, moved to {@link fully qualified path}
Some other reason	As of version, because of some reason

Javadoc Linking

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.

Formatting Tags

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 {
	...
}

Home
Architecture & Infrastructure
- Roadmap
- Technology Stack
Developer Guides
- Development & Testing
  - Testing Overview
  - Testing the Docker Image
- Javadoc Format
- Releasing
  - Performing a Release

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Javadoc Guidelines

Table of Contents

Class Javadoc

Class Descriptions

Class Javadoc Tags

@param tags

@see tags

@since tags

@deprecated tags

Method Javadoc

Method Descriptions

Short Description Sentence

Longer Descriptions

Method Javadoc Tags

@param tags

@return tags

Abbreviating return description when extensive matching done

Parameter Side Effects

@throws tags

@see tags for methods

@since tags for methods

@deprecated tags for methods

Javadoc Linking

Formatting Tags

Clone this wiki locally