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