On 12/12/2007, jerry gay <[EMAIL PROTECTED]> wrote:
> On Dec 11, 2007 11:08 PM, Andy Lester <[EMAIL PROTECTED]> wrote:
> > I made it make comment blocks look like this:
> >
> > /*
> >
> > =item C<QUEUE_ENTRY * pop_entry>
> >
> > Does a synchronized removal of the head entry off the queue and
> > returns it.
> >
> > =cut
> >
> > */
> >
> > PARROT_CAN_RETURN_NULL
> > QUEUE_ENTRY *
> > pop_entry(ARGINOUT(QUEUE *queue))
> > {
> > ... function body...
> >
> a good start.
>
> > Does anyone actually run something like perldoc src/filename.c to
> > look at the docs? I'm thinking that if nobody actually does that, we
> > could save the doc discussion until we're actually at a point where
> > we're generating docs. Right now, I think that what I've got as the
> > prototype above is 90% there, and gets rid of the tons of cut'n'paste
> > that are sprinkled throughout the C code.
> >
> > Let me know your thoughts, so I can do more automation and run it on
> > the rest of the source files.
> >
> nobody really looks at docs in generated .c files, we go to the source
> (.pmc, .ops, .in, etc.) why don't you finish the plumbing, and we'll
> save the bickering for when the information is flowing everywhere we
> need.
AFAIK, at least some of the C docs are automatically turned into html
and posted on parrotcode.org (I could be mis-remembering something
here though). But it's hard to know how many people use that. I know
that a lot of the docs which *could* be posted to parrotcode.org (i.e.
via 'make html') unfortunately aren't.
> once we've decided on a standard doc style, let's document it in PDD07
> so it's law.
Hadn't we decided on that? Basically, add everything in? That's why
I did the effort of the C function docs tests... I would rather the
process of updating the docs be automated though. (BTW: Andy: great
job on the function declaration extraction stuff! It helped
enormously in getting refactoring some of the common code out into a
module, and then reusing it in the c-function docs test).
My apologies that I've not got around to implementing this myself, as
I intended to as you were away Andy, but my tuits are now at the level
of just keeping the coding standards tests running...
Paul
