Missing C Function Documentation
The following is extracted from the test t/codingstd/c_function_docs.t.
If the test fails it will give the C source file in single quotes, followed by the output for the test - prefixed by #
It gives the number of functions missing documentation in the source file, then the function(s) missing documentation, and what the test expects to be there (Want:).
The want: part gives what the documentation header is expects.
of the form:
# =item C<function_name(parameters) # it may be wrapped onto a second line if it exceeds 80 characters
It should be noted that lib/Parrot/Headerizer.pm which is used by the t/codingstd/c_function_docs.t to extract and test C function Docs imposes a line length of 80 characters on the =item header in the documentation. If the documentation does not conform to this it will fail the test. The =item header must be less than 80 characters or wrap at 80 characters. (Cases where the =item header wraps before 80 characters [i.e. if a word in the header which would be allowed up to 80 characters is on the next line - the test will fail at present]).
The documentation is expected to have something similar to the following format in a C function:
/* =over 4 =item C<function name and parameters wrapped at line 80> some documentation (preferably, but not necessarily, wrapped at line 80) =back =cut */ function header here
The =over 4 is not required if a previous =over 4 exists without a =back which needs to be in the last entry.
A series of related functions may be grouped together. For example:
/* =over 4 =item C<function 1 header> =item C<function 2 header> ... Documentation for function 1 and function 2 ... ... =back =cut */ function 1 here ...