[DOCS] Updated documentation in src

[Michael Scott]

I've add inline docs to everything in src (except for malloc.c and
malloc-trace.c).

At times I wondered whether this was the right thing to do. For
example, in mmd.c, where Dan had already created a mmd.pod, I ended up
duplicating information. At other times I reckoned that what was needed
was an autodoc. Other times the best I could do was rephrase the
function name. All issues to address in phase 2.

Next I think, for a bit of light relief, I'll do the examples.

For those who want to browse:

http://homepage.mac.com/michael_scott/Parrot/docs/html/

Mike

[Matt Fowles]

Mike~

You rock. That is really nice.

Matt

[Leopold Toetsch]

Matt Fowles <Matt_...@softhome.net> wrote:

[ another TOFU [1] ]

AOL

leo

> Mike~

> Matt

[1]

German: Text oben, fullquote unten - a posting style I don't like
(and an ETLA that very likely doesn't deserve more translation :) -
*but* there are of course exceptions ;)

[Vishal Vatsa]

On Thursday 29 January 2004 18:20, Michael Scott wrote:

> For those who want to browse:
>
> http://homepage.mac.com/michael_scott/Parrot/docs/html/
>
> Mike

Thanks....
you defn. rock...
--
Vishal Vatsa
Dept. of Computer Sc.
NUI Maynooth

[Tim Bunce]

Would doxygen be of use here? http://www.doxygen.org/

Here's an example use http://www.speex.org/API/refman/speex__bits_8h.html#a2
Follow the links, including to the annotated source file.

Tim.

[Michael Scott]

I haven't ruled out something like that in the long term, but what I'm
trying achieve at the moment is just to see some pod everywhere. This
has the merit that I visit every file and ensure that some basic
information gets provided for the newbies - my target audience.

In a sense I'm following the time honoured tradition of throwing one
away, namely the Getting Started Guide on the wiki. I'm shifting pod
from there into the files.

At the moment I'm just building a big index.html list and using the
default html formatting from Pod-Simple, but this will change soon.

I think the trick is to model the project with perl modules so that
it's straightforward to extract and compose information. I already have
the basis for this, which I'll check in any day now.

Mike

[Tim Bunce]

Great, thanks.

Tim.