Apex documentation best practices

This article is based on the PMD documentation article. See the original article on the PMD site: PMD: documentation best practices.

Below are the generally accepted best practices. 

ApexDoc

This rule validates that:

  • ApexDoc comments are present for classes, methods, and properties that are public or global, excluding overrides and test classes (as well as the contents of test classes).
  • ApexDoc comments should contain @description.
  • ApexDoc comments on non-void, non-constructor methods should contain @return.
  • ApexDoc comments on void or constructor methods should not contain @return.
  • ApexDoc comments on methods with parameters should contain @param for each parameter, in the same order as the method signature.

Method overrides and tests are both exempted from having ApexDoc.

This rule is defined by the following Java class: 

net.sourceforge.pmd.lang.apex.rule.documentation.ApexDocRule

Example

/**
 * @description Hello World
 */
public class HelloWorld {
    /**
     * @description Bar
     * @return Bar
     */
    public Object bar() { return null; }
}

Properties

NameDefault ValueDescriptionMultivalued
cc_categoriesStyleCode Climate Categoriesyes. Delimiter is ‘|’.
cc_remediation_points_multiplier1Code Climate Remediation Points multiplierno
cc_block_highlightingfalseCode Climate Block Highlightingno

What's here


Related content

 PMD: documentation best practices




Last modified on Jul 14, 2020