| 1 | 807 Each source file (e.g. a F<foo.c>, F<foo.h> pair), should contain inline |
|---|
| 2 | 808 Pod documentation containing information on the implementation decisions |
|---|
| 3 | 809 associated with the source file. |
|---|
| 4 | ... |
|---|
| 5 | 865 =item Per-entity comments |
|---|
| 6 | 866 |
|---|
| 7 | 867 Every non-local named entity, be it a function, variable, structure, macro or |
|---|
| 8 | 868 whatever, must have an accompanying comment explaining its purpose. This |
|---|
| 9 | 869 comment must be in the special format described below, in order to allow |
|---|
| 10 | 870 automatic extraction by tools - for example, to generate per API man pages, |
|---|
| 11 | 871 B<perldoc -f> style utilities and so on. |
|---|
| 12 | 872 |
|---|
| 13 | 873 Often the comment need only be a single line explaining its purpose, but |
|---|
| 14 | 874 sometimes more explanation may be needed. For example, "return an Integer Foo |
|---|
| 15 | 875 to its allocation pool" may be enough to demystify the function C<del_I_foo()> |
|---|
| 16 | 876 |
|---|
| 17 | 877 Each comment should be of the form |
|---|
| 18 | 878 |
|---|
| 19 | 879 /* |
|---|
| 20 | 880 |
|---|
| 21 | 881 =item C<function(arguments)> |
|---|
| 22 | 882 |
|---|
| 23 | 883 Description. |
|---|
| 24 | 884 |
|---|
| 25 | 885 =cut |
|---|
| 26 | 886 |
|---|
| 27 | 887 */ |
|---|
