Re: [DOCS] Updated documentation in src
Great, thanks. Tim. On Sat, Jan 31, 2004 at 01:05:02AM +0100, Michael Scott wrote: 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 On 30 Jan 2004, at 19:23, Tim Bunce wrote: 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. On Thu, Jan 29, 2004 at 07:20:50PM +0100, Michael Scott wrote: 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
Re: [DOCS] Updated documentation in src
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
Re: [DOCS] Updated documentation in src
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. On Thu, Jan 29, 2004 at 07:20:50PM +0100, Michael Scott wrote: 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
Re: [DOCS] Updated documentation in src
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 On 30 Jan 2004, at 19:23, Tim Bunce wrote: 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. On Thu, Jan 29, 2004 at 07:20:50PM +0100, Michael Scott wrote: 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
[DOCS] Updated documentation in src
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
Re: [DOCS] Updated documentation in src
Matt Fowles [EMAIL PROTECTED] wrote: [ another TOFU [1] ] AOL leo Mike~ You rock. That is really nice. Matt Michael Scott wrote: 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 [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 ;)
