* Hinrik ??rn Sigur??sson (hinrik....@gmail.com) [090504 10:45]:
> In Perl 5 I hate having Pod interleaved with code, since it is usually
> mostly /user/ documentation and so just gets in the way. Having normal
> Pod elsewhere (at end-of-file or in a different file) and keeping API
> Pod docs inline (and having tools which might merge the two into nice
> HTML if desired) would be the best of both world.
I also maintain old and often used modules written by experienced
programmers, which did have the POD and the end of the file and in
seperate files. Transforming that into interleaved documentation
highlighted many mistakes: often, over time, the interface gets extended
or deprecated. When the documentation is far away from the code, people
forget to update it. That is a fact. Besides, user-doc and code-doc
have quite some overlap. By interleaving user-doc with the code, you need
less code-doc to achieve the same clarity.
On the other hand, you also need a global API description, which
demonstrates how the various functions/methods work together. So in my
personal favorit style, I document the nasty details of each method close
to the code of the method, and after all the code I add a long text on
all the main subjects of the code, on how to use the module as a whole.
In that large text, I do not wish to detail all the options because that
frustrates the learning process.
--
Regards,
MarkOv
------------------------------------------------------------------------
Mark Overmeer MSc MARKOV Solutions
m...@overmeer.net soluti...@overmeer.net
http://Mark.Overmeer.net http://solutions.overmeer.net
