Method Header Comments

The following is an example of documentation conventions for method header comments, which are also suitable for PeopleCode. It contains comment tags, which are explained below the example.

/**
  * Description of what method does
  *
  * @param a optional description of param a
  * @param b optional descriptions of param b
  * @exception PrivilegeException thrown if etc, etc
  * @exception SQLException thrown if etc., etc.
  * @return String  -  description of potential values
  */
Method myMethod
   ...
End-method;

Method Comment Tags

The following are the suggested tags for commenting methods.

Tag	Description
@param N	Specify a description for each method parameter. The name of the parameter is specified after the keyword @param.
@exception name	Specify a description of each exception class. The name of the exception is specified after the keyword @exception. For example, the descriptions can explain what causes certain exceptions to be thrown.
@return Type	Specify a description of the return value. The type of data that is returned is specified after the keyword @return. For example, explain the potential values a method may return, whether it returns null in some circumstances, and so on.

Not all methods require documentation. For example, some simple set or get methods have method signatures that are descriptive enough. In other cases, it may suffice to include a brief sentence in the header explaining what the method does.

As with methods, PeopleCode get or set blocks should also carry method header comments.