I fully agree with David's response to this mail. The only
thing I would like to add:
* Smylers ([EMAIL PROTECTED]) [070621 18:02]:
> [*0] Consider a function C<valid_postcode>. I'd document it along
> the lines of:
>
> valid_postcode
>
> Returns whether the specified postcode is valid, for example:
>
> if (valid_postcode $postcode) {
>
> Javadoc-style systems seem to insist on documentation like:
>
> valid_postcode
> Description: Returns whether the specified postcode is valid.
> Parameters:
> $postcode: (string) The postcode to test for validity
> Returns: (boolean) Whether $postcode is valid
> Exceptions: none
> Side Effects: none
Of course, you can write horrible documentation in any syntax: that's
up to the authors. But now, just try to write above documentation in
the new POD6 syntax... in that case, it is not only horrible documentation,
but also 2 pages long.
In my idea, it suffices to write:
method isValidPostalCode(str $postalcode) returns bool {...}
By introspection during manual-page creation, it can collect
sufficient information to create this documentation item (controlled
by a (user-provided) template). With the POD back-end, something like
(blank lines removed)
=head1 METHODS
=over 4
=item $obj->isValidPostalCode(str $postalcode) returns bool
=back
Then, when you want to add some docs to the method, to help the
correct use, add it, for instance like:
method isValidPostalCode(str $postalcode) returns bool {...}
` Check wether the postal code confirms to the standards
`$postalcode: a string with blanks trimmed.
`return: the string is not cleaned-up.
or maybe (exact syntax open to discussion)
method isValidPostalCode(str $postalcode) returns bool {...}
#= Check wether the postal code confirms to the standards
#=$postalcode
#= a string with blanks trimmed.
#=return
#= the string is not cleaned-up.
or
method isValidPostalCode(str $postalcode) returns bool {...}
// Check wether the postal code confirms to the standards
//
// $postalcode a string with blanks trimmed.
// return the string is not cleaned-up, if you need
// that, call M<cleanupPostalCode()>.
or maybe at the bottom of your file, whatever you like
__DOC__
=doc isValidPostalCode
Check wether the postal code confirms to the standards
$postalcode a string with blanks trimmed.
return the string is not cleaned-up, if you need
that, call M<cleanupPostalCode()>.
There is so much user-friendliness to gain.
Very condensed documentation. Of course, you will get simple ways to
change the default mark-up of the parameters, for instance for the case
of MMD's, huge parameter lists, or where the parser cannot figure-out
info automatically.
--
Regards,
MarkOv
------------------------------------------------------------------------
Mark Overmeer MSc MARKOV Solutions
[EMAIL PROTECTED] [EMAIL PROTECTED]
http://Mark.Overmeer.net http://solutions.overmeer.net
