[prev in list] [next in list] [prev in thread] [next in thread] 

List:       phpdoc
Subject:    Re: [PHP-DOC] Re: cvs: phpdoc /scripts xml_proto.php
From:       Philip Olson <philip () roshambo ! org>
Date:       2007-08-29 22:12:18
Message-ID: 6D598BE7-0CAD-4DB2-B9F7-52679B9B6AD2 () roshambo ! org
[Download RAW message or body]


On Aug 28, 2007, at 1:58 AM, Jakub Vrana wrote:

> M. Sokolewicz wrote:
>> A lot of people might not know the info is there, but instead of
>> removing it entirely I would suggest using an option to enable/ 
>> disable
>> it. The skeleton created should still be obvious to people who do not
>> know much (if anything) about the way php-doc is made. So IMO it's  
>> not
>> obvious to everyone that the description of that paremeter should go
>> into that <para></para> section. Adding a switch (defaulting to  
>> off if
>> you wish) would make it easier to create one with extra "debug" info
>> which is useful to write the actual documentation. If people just  
>> want a
>> raw skeleton, with _no_ additional manual editing involved, they  
>> should
>> run it with a different flag/option/switch.
>
> What about just put it inside a comment?
>
>              "     <listitem>\n" .
>              "      <para>\n" .
> +            "       <!-- Its description -->\n" .
>              "      </para>\n" .
>              "     </listitem>\n" .

I feel people know what goes there, and don't find it nice to delete  
the phrase so many times. And when writing documentation people  
typically (should) go by the skeletons in the HOWTO or Wiki (which do  
contain the additional information) or use currently written  
documentation. Either way, I don't see cause for confusion and  
instead find people committing it as is, or being annoyed by having  
to delete it. After documenting one parameter, a person should know  
what goes there.

I don't mind creating an xml_proto switch to allow it but would like  
to see it default to off. Feel free to create this and if done please  
apply it to the other sections too (like examples). The comment idea  
is okay, but I prefer not.

Regards,
Philip
[prev in list] [next in list] [prev in thread] [next in thread]