Stas Bekman wrote:
> If you follow the docs-cvs mailing list you have noticed that I've been
> working recently on writing the doc on writing tests. The problem is
> that I cannot decide where the documents should go:
>
> On one side we need to have inlined docs of the functions so one can
> easily lookup needed features via 'perldoc modulename'. This is a
> reference mode.
>
> On the other side, we want to produce a sequential document where one
> can learn things by reading a structured document. This is a tutorial mode.
>
> I really want to try to avoid to duplicate documentation. As you realize
> that it's a nightmare to maintain.
>
> What do you think is the best approach we should use?
>
> So far I've documented Apache::TestUtil inline and started to document
> Apache::Test as an external doc, which is a part of a bigger doc.
Since a big chunk of the code is autogenerated and there are many files
which get created from the air (there is no source) file, it would be
quite hard to document the API inline.
API has to be kept short and clean, without spreading the references to
it, so it's easy to correct API changes. Something that's very hard if
we put API into user's docs.
Therefore, the original Doug's preference (having a separate .pod file
for each module) seems to be the best choice.
I'm going to create modperl-docs/src/api and move all the existing API
documentation there. Just like Perl does, so Apache::TestUtil's pod will
end up as modperl-docs/src/api/Apache/TestUtil.pod and
Apache::RequestRec will be documented at
modperl-docs/src/api/Apache/RequestRec.pod. Here is a more visual example:
modperl-docs/src/api/Apache/TestUtil.pod
modperl-docs/src/api/Apache/Test.pod
modperl-docs/src/api/Apache/RequestReq.pod
modperl-docs/src/api/APR/Table.pod
There is one nuance is whether to pile all the projects together as
suggested above or to have yet another sub-tree for each project:
modperl-docs/src/api/Apache-Test/Apache/TestUtil.pod
modperl-docs/src/api/Apache-Test/Apache/Test.pod
modperl-docs/src/api/modperl-2.0/Apache/RequestReq.pod
modperl-docs/src/api/modperl-2.0/APR/Table.pod
and so-on... how do you prefer?
_____________________________________________________________________
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]
