develooper Front page | perl.perl5.porters | Postings from August 1999

Re: perlfunc annonations or OOB enhancements?

Adam Turoff
August 27, 1999 17:46
Re: perlfunc annonations or OOB enhancements?
Message ID:
Tom Christiansen wrote:
> >Better documentation.  These descriptions must be highly regular, so
> >deriving a reference card or better preambles for HTML/manpages shouldn't
> >be too difficult.
> But the documentation *does* have all that, just not all in the same place.
> I also don't think it's all that automatable.  Where does localtime's 0..59
> range on minutes and seconds get indicated, for example?  If you look at
> Johan Fromans's quickref, it's written in hand-crafted troff.  As for
> classes, this becomes even dicier, since it's all dynamic, indirect
> function calls.

Johan documents 0..11 and 0..6 in prose, not in the line which says
localtime [ EXPR ].  Moving to more descriptiveness is *better*, 
not optimal.  Describing every nuance is not possible, given that
the objetive is to keep POD somewhat plain.  Prose documentation 
will exist and will still need to exist.  

Adding context-sensitive function descriptions can display the
order of the parameters when you're not sure whether $year is
item 4 or item 5, but *do* remember that it is year - 1900.  I'd say
that this is a common case.

-- Adam Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About