Re: Documentation trait / Docstring equiverlent
Larry Wall <larry <at> wall.org>
2005-07-02 17:13:19 GMT
On Sat, Jul 02, 2005 at 10:17:01AM -0600, John Williams wrote:
: There is something to be said for actually _organizing_ the documentation
: too, which is why POD docs for a function are not always next to the
: function itself.
I always cringe when I hear "the documentation", as if it's only one thing.
: That said, I hope the documentation trait on subs can optionally be a
: pointer to the (section of the POD) document where the documentation
: actually resides.
We'll certainly make that possible, though going that direction is
a little problematic insofar as it's pretty easy for the document to
link to a function that already has a name that is unlikely to change,
whereas it's difficult for a function to point into a document where
the section numbers are changing, unless you come up with some kind of
naming scheme for document sections, which by and large comes out to
naming the sections with the same long name as the routines.
If you store the doc info with the function, then you also have the
ability to massage it different ways and autogenerate sections of
your docs without having to have an explicit doc specifying the order
of every entry. Of course, from the document-centric point of view
these are just slicing operations, which can be based on either rules
or enumerations. But if we want to slice by rule, the functions have
to have at least enough associated metadata to specify the slicing
rules.
But going back to the "must have the same name" idea, names are just
keys into something, so this kinda smells to me like parallel hashes
(Continue reading)