Ticket #1726: c_function_codingstd.extract.txt

File c_function_codingstd.extract.txt, 1.0 KB (added by jkeenan, 4 years ago)

Extract of docs/pdds/pdd07_codingstd.pod re documentation of C functions

Line 
1807 Each source file (e.g. a F<foo.c>, F<foo.h> pair), should contain inline
2808 Pod documentation containing information on the implementation decisions
3809 associated with the source file.
4...
5865 =item Per-entity comments
6866
7867 Every non-local named entity, be it a function, variable, structure, macro or
8868 whatever, must have an accompanying comment explaining its purpose.  This
9869 comment must be in the special format described below, in order to allow
10870 automatic extraction by tools - for example, to generate per API man pages,
11871 B<perldoc -f> style utilities and so on.
12872
13873 Often the comment need only be a single line explaining its purpose, but
14874 sometimes more explanation may be needed. For example, "return an Integer Foo
15875 to its allocation pool" may be enough to demystify the function C<del_I_foo()>
16876
17877 Each comment should be of the form
18878
19879     /*
20880
21881     =item C<function(arguments)>
22882
23883     Description.
24884
25885     =cut
26886
27887     */