Based on the silence == assent prinicple, I think we have agreed:
1. we need "a relatively strict and standard way" to document code.
2. This is the time and place to discuss it.
3. The result of the discusssion should be a PDD.
4. Most commentary should appear within the src file itself, or it's useless.
5. Broad agreement with my proposal for mandatory per file, per section,
and per func/struct comments.
5a. Most of the structured comments should be extractable, even if we
don't immediately make use of them. Obviously stuff that would be meaningless
on its own shouldn't be extracted.
Since this as all agreed, we can now move onto 6:
> 6. Can we leave the details of pod/apidoc/rfc281 until 1..5 have been
> agreed?
ie we thrash this bit out, then I'll write it up as an improved version
of the PDD I scribbled earlier and submit it (now that I know how to
submit PDDs :-)
So here goes....
I want to combine:
* "we need comments in the code" - me and a cast of thousands
* "we need a commentary file per src file" RFC281 and Simon Cozens
* "we need PDDs" - Dan and everyone
into a 3-layer hierarchy.
Take something like the IO system. At the top level, we have a PDD on
IO saying [this example is totally fictional]:
"we considered async, event, blah, etc but decided on async for the
following reasons: blah blah.
IO is be implemented by having a system-independent layer with
the following API, and...."
ie a high-level document covering a whole subsystem.
When people code up the IO subsystem, they will end up with a collection
of src files, each implementing various aspects of it. Each (or most) src
file has an associated (but separate) file providing an overall commentary
for the code that is in the file. This describes low-level design decisons
and histories for the things implemented in that file. Eg it might say:
"We maintain a cache of IO handles, as it was found that this speeded
up blah blah."
Finally, there would be the individual comments within the source file.
Here, a section comment would be more specific to the here-and now coding,
eg
"This section implements the IO handle cache. It is maintained as a
doubley-linked list with IO_handle_root pointing to the head.
pop_io_handle() grabs the most recent handle by simply yanking it from
the head of the list, while push_io_handle() returns it to the head
unless..."
and the per-function comment for pop_io_handle() would say
/* grab most recently used handle from the handle cache */
I would expect that the sort of level of information provided by something
like perlguts.pod would naturally find its way spread between a PDD and
commentary file, while the comments in the src file itself are at a
lower level.
---|---
So, we need to decide whether we want a 3-level hierarchy like that
suggested, and once agreed, the stucture and/or tagging of the
commentary file and src comments.
