Re: [svn:perl6-synopsis] r14421 - doc/trunk/design/syn 
I fully agree with David's response to this mail.  The only
thing I would like to add:

* Smylers (Smylers@stripey.com) [070621 18:02]:
>   [*0]  Consider a function C.  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.

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.

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
       Mark@Overmeer.net                          solutions@overmeer.net
http://Mark.Overmeer.net                   http://solutions.overmeer.net

