'''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
...
}}}