Per-entity comments

[Michael Scott]

I wonder does anyone want to think about the "Per-entity comments"  
section In PDD 7?

------------------------------------------------------------------------ 
-------------------------------------------
Per-entity comments

Every non-local named entity, be it a function, variable, structure,  
macro or whatever, must have an accompanying comment explaining it's  
purpose.  This comment must be in the special format described below,  
in order to allow automatic extraction by tools - for example, to  
generate per API man pages, perldoc -f style utilities and so on.

Often the comment need only be a single line explaining its purpose,  
but sometimes more explanation may be needed. For example, ``return an  
Integer Foo to its allocation pool'' may be enough to demystify the  
function del_I_foo()

Each comment should be of the form

    /*=for api apiname entityname[,entityname..] flags ....(TBC)....
    comments....
    */
where apiname is the API the entity belongs to, eg pmc, and entity name  
is the actual name of the function or macro or whatever. Where there is  
a whole family of entities that have the same properties and can be  
collectively described with a single comment, a list of entity names  
can be provided.

TBC ...
------------------------------------------------------------------------ 
-------------------------------------------

A real life example of this can be found in hash.c:

    /*=for api key key_hash

    Return the hashed value of the string

    =cut */

Presumably, the idea was to prepare for a yet-to-be-written parrotdoc  
utility which would find, extract and format the pod a la perldoc -f.

An alternative example of pod in C comments can be seen in packfile.c.  
A list is set up at the start of the file, and subsequent comments are  
written as:

    /***************************************

    =item pack_size

    Determine the size of the buffer needed in order to pack the  
PackFile
    Constant into a contiguous region of memory.

    =cut

    ***************************************/

The nice thing about this is that it allows the pod to be viewed by  
passing the C file through pod2html.

http://www.vendian.org/parrot/source/?op=pod2html&file=packfile.c

In hash.c, because the pdd7-style comments are cuddled up against the C  
comment delimiters they don't work as pod.

It wouldn't be difficult to convert existing pdd7-style comments so  
they work with pod2html - just leave the =for api line cuddled and  
follow it with an =item line for the entity.

    /*=for api key key_hash

    =item key_hash

    Return the hashed value of the string

    =cut

    */

This would leave the api info available for parrotdoc when it appears.

The pod literate among you will quickly spot that this solution drops  
the comment outside the scope of the =for line, but given that some of  
the existing comments already include multiple paragraphs I think that  
can be left as a design issue for the parrotdoc team.

I would be happy to make these changes if they were felt to be a good  
thing.

The files touched would be

    parrot/datatypes.c
    parrot/hash.c
    parrot/interpreter.c
    parrot/memory.c
    parrot/pmc.c
    parrot/register.c
    parrot/runops_cores.c
    parrot/string.c
    parrot/trace.c
    parrot/types/bignum.c
Apart from the fact that the change would allow me put links to this  
documentation into the Getting Started guide, I'm raising this issue  
because it troubles me that PDD 7 says that per-entity comments should  
be there, and should be done in a particular way, without giving any  
real motivation or justification.

Mike