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