C function documentation

The test t/codingstd/c_function_docs.t checks for documentation relating to C functions.

It performs two functions:

Firstly it scans the C source for functions in parrot and checks that each function has documentation associated with it and reports it missing if it does not find the corresponding documentation. It reports - (missing).

Secondly, it checks that there is content in the documentation, if it does not find content, i.e. only the header (=item C<...>) exists. It reports - (boilerplate only).

As at r47918 there are now no remaining functions in the repository that do not have the required documentation.

Previously I had compiled a report on the current functions missing MissingCFunctionDocs documentation and of those lacking (boilerplate only) BoilerplateOnlyDocs documentation.

For the moment these links will remain as they will document how to correct the documentation if the test fails at any stage in the future.

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.

If the documentation is corrected (patched) the test t/codingstd/c_function_docs.t has a TODO list for the failures (in the DATA section at the end) and if corrected the corresponding entry needs to be removed from the test.


this list is now empty as at r47918 and hopefully will remain so.