On Sat, 23 Jun 2001, brian moseley wrote:
> would you really trust somebody to write docs that you
> wouldn't trust to write code? i wouldn't. so i don't think
> it should be a concern.
i don't know if 'trust' is the right word. the code/docs split approach
has been working well for the httpd project. maybe we don't need todo the
same, we can think about it.
> why exactly would one release docs separately? i don't see
> it happening in reality. keep them in the core module.
the docs will be shipped with the modperl distribution, but at some point
docs will probably be update more often than modperl releases. so the
idea was that docs could have their own release which could go out
whenever. of course, then we have the problem of docs containing docs
based on the code in cvs, not the current release of modperl.
> i highly prefer having module doc inline. and i mean inline,
> interspersed amongst subs, so i can see the doc for a sub
> when i'm looking at its code. i get annoyed when i have to
> scroll to the bottom or open a second window to look at the
> doc for a sub :)
i have the opposite feeling, docs interspersed amongst subs drives me
crazy. but if enough people prefer that, i can deal. the majority of the
api docs for 2.0 will be in the form of pod/modules/Apache/Foo.pod
since the majority of the api is generated, including the Foo.pm's
so i was thinking we should have all modules be documented in their own
.pod, so all docs are in the same place. but again, i can be convinced
otherwise for the pure-Perl modules that are written by hand.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
