On Mon, 25 Jun 2001, Doug MacEachern wrote:
> On Sun, 24 Jun 2001, Stas Bekman wrote:
>
> > So what do we decide about documentation style, so we can start
> > documenting things as we go? As I've replied to brian's email, I'm in
> > favor of inline docs if it doesn't make the code harder to read.
>
> that's fine, i still would rather see each module have its own .pod, but
> will go with the flow if inline is prefered.
let's try to go with the inlines first, if we see that it's not good. we
extract all the inlines into the separate .pod files. This is something
that we can do much easier than the reverse operation, assuming that we
want the snippets of pod to be scattered around the code.
The good thing about inlines is that there is a better chance that the
inline docs will be updated on code updates.
For distributions we can have all docs in .pod files. We'll make sure that
we have .pod, .html, .ps, .pdf, (.xml?) and other formats available on
demand.
> > Also Doug you were talking about self-documenting code, I don't remember I
> > saw any details about this thingy in the docs. Can you elaborate on this?
>
> by that i literally meant 'self-documenting code'. like you can
> get a good understanding of the modperl C code just by reading the code.
> granted docs for the C api would be nice, hopefully attempting to write
> 'self-documenting code' will make that easier.
Oh, I see :) From your original conference paper doc I understood that you
plan to autogenerate docs from the API code. I thought that would be
cool, but now I know that it was an illusion :)
_____________________________________________________________________
Stas Bekman JAm_pH -- Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide http://perl.apache.org/guide
mailto:[EMAIL PROTECTED] http://apachetoday.com http://eXtropia.com/
http://singlesheaven.com http://perl.apache.org http://perlmonth.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
