Changes between Version 4 and Version 5 of MissingCFunctionDocs

Timestamp:

06/30/10 01:04:12 (12 years ago)

Author:

mikehh

Comment:

--

MissingCFunctionDocs

@@ -3 +3 @@
 The following is extracted from the test t/codingstd/c_function_docs.t.
 
-The following gives the C source file in single quotes, followed by the output for the test - prefixed by #
+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:).
 
-Bear in mind we are dealing with POD and that it expects a maximum line length of 78.
+The want: part gives what the documentation header is expects.
 
-as of r44170 the following C functions are missing documentation:
+of the form:
 {{{
-All current functions have at least (boilerplate only) or valid documentation
+# =item C<function_name(parameters)
+# it may be wrapped onto a second line if it exceeds 80 characters
 }}}
+
+Bear in mind we are dealing with POD and that it expects a maximum line length of 80.
+
+The documentation requires the following format in a C function:
+
+{{{
+/*
+
+=over 4
+
+=item C<function name and parameters wrapped at line 80>
+
+some documentation (again 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.