With the exception of subroutines and functions that have been identified as private or local, the header documentation should always specify an argument as either ‘required’ (keyword REQ) or ‘not required’ (keyword NOREQ). If an argument is required but a <null> value is not allowed, the documentation should specify this using the keyword NONUL (if not specified, the default is <null> values are allowed). Refer to the Symbol and Keyword Definitions section in the Profile Programming Standards online Help for more details.
Header documentation is required for public subroutines and functions, and it is strongly recommended for private and local subroutines and functions.
It is not necessary to specify the data type (keyword TYP) in the header documentation for an argument that passes an object, because the data type is specified in the argument itself.
Properly documenting the arguments provides the following benefits:
Provides better definitions of APIs by eliminating ambiguity
Eliminates the need to include unnecessary edit checks in the source code (e.g., to determine if the argument is defined or if it has a <null> value)
Clearly places responsibility on the calling routine to ensure the arguments fulfill the requirements of the subroutine/function that is being called
When Standard is Enforced: Profile v7.0