On Tue, 26 Jun 2001, Stas Bekman wrote:
> 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.
oh yeah, that's another reason i was thinking of having module docs be in
their own .pod file, for the docs distribution. if the pod is inlined in
the .pm, will you extract that into a Module.pod for the docs dist?
and then, if you install a doc kit that's new than the code, does
'perldoc Module' pickup the new Module.pod or pod inside Module.pm?
> > > 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 :)
that was not an illusion, i did say API docs can be generated, and they
still can be. 'autogenerated docs' and 'self-documenting code' are two
very different things. i mentioned 'self-documenting code' in a recent
offlist message when you asked about documentation for understanding the
core code.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
