Missing entry in Apex documentation
Why is this an issue?
ApexDoc comments that are incomplete make code harder to understand and maintain:
Missing @param: Callers don't know what parameters to expect
Missing @return: Return value meaning is unclear
Missing @throws: Exception handling requirements are unknown
Incomplete documentation is sometimes worse than no documentation because it creates false confidence.
Examples
Example of incorrect code:
/**
* Calculates the total price with tax
*/
public Decimal calculateTotal(Decimal price, Decimal taxRate) {
if (price < 0) {
throw new IllegalArgumentException('Price cannot be negative');
}
return price * (1 + taxRate);
}
Example of correct code:
/**
* Calculates the total price with tax
* @param price The base price before tax
* @param taxRate The tax rate as a decimal (e.g., 0.20 for 20%)
* @return The total price including tax
* @throws IllegalArgumentException if price is negative
*/
public Decimal calculateTotal(Decimal price, Decimal taxRate) {
if (price < 0) {
throw new IllegalArgumentException('Price cannot be negative');
}
return price * (1 + taxRate);
}
How can I fix violations?
Add @param for all parameters: Document each parameter's purpose and expected values.
Add @return for non-void methods: Describe what the return value represents.
Add @throws for exceptions: Document exceptions the method may throw.
When should I disable this rule?
You may dismiss violations if your team uses different conventions around Apex documentation.
Resources