Re: #20068 [NEW]: PHPDoc short line is confusing

use phpDocumentor. It will handle the short and long descriptions properly. http://www.phpdoc.org Greg <mattb@columbia.edu> wrote in message news:bug-20068@bugs.php.net... > From: mattb@columbia.edu > Operating system: GNU/Linux 2.4.18-17.7.x (RedHat) > PHP version: 4.2.3 > PHP Bug Type: PEAR related > Bug description: PHPDoc short line is confusing > > I'm not sure what the intention was with the short vs. long description in > PHPDoc, but the implementation seems to cut it off after the first line > which yields some interesting documentation (even in PEAR's own classes). > For example, take the following comment from PEAR.php: > > /** > * Constructor. Registers this object in > * $_PEAR_destructor_object_list for destructor emulation if a > * destructor object exists. > * > * @param string (optional) which class to use for error objects, > * defaults to PEAR_Error. > * @access public > * @return void > */ > function PEAR($error_class = null) > { > ... > > When PHPDoc is run, this var is listed in the Public Method Summary as: > > void PEAR([ string $error_class ]) > Constructor. Registers this object in > > Then in Public Method Details, it is listed as: > > PEAR > public void PEAR([ string $error_class ]) > > $_PEAR_destructor_object_list for destructor emulation if > a destructor object exists. > > ... > > Somehow, I doubt this was the intention of the author to have this > particular comment broken up like this. > > I also noticed that empty lines had no significance in PHPDoc. For > example, the following comment: > > /** > * This is the summary line. > * > * This is one paragraph. > * > * This is another completely unrelated paragraph. > */ > > In the details, this will be rendered as: > > This is one paragraph. This is another completely > unrelated paragraph. > > If I may make a suggestion: it seems like both of the above problems would > be solved if the following expression had significance as a separator > within PHPDoc comments: > > "\n[[:space:]]*\*?[[:space:]]*\n" > > In other words, blocks of text separated by a line that was either empty, > composed of spaces or of a '*' optionally with spaces on either side would > denote the end of a paragraph. The first paragraph could be that which > belongs in the summary. Subsequent paragraphs could be rendered > appropriately with breaks in the detail. Here's an example: > > /** > * This is the summary paragraph. It can span several > * lines, but since it's part of the same paragraph, it's > * okay. > * > * This is the first detail paragraph. It can also span > * several lines, but that's okay too. > * > * This is another detail paragraph. All of these can > * span multiple lines...it's the notion of being > * separated by "blank" lines which makes them distinct. > */ > > This would be rendered as follows: > > Summary > > This is the summary paragraph. It can span several lines, > but since it's part of the same paragraph, it's okay. > > Detail > > This is the first detail paragraph. It can also span > several lines, but that's okay too. > > This is another detail paragraph. All of these can span > multiple lines...it's the notion of being separated by > "blank" lines which makes them distinct. > > Just my two cents...I hope this is helpful. > -- > Edit bug report at http://bugs.php.net/?id=20068&edit=1 > -- > Try a CVS snapshot: http://bugs.php.net/fix.php?id=20068&r=trysnapshot > Fixed in CVS: http://bugs.php.net/fix.php?id=20068&r=fixedcvs > Fixed in release: http://bugs.php.net/fix.php?id=20068&r=alreadyfixed > Need backtrace: http://bugs.php.net/fix.php?id=20068&r=needtrace > Try newer version: http://bugs.php.net/fix.php?id=20068&r=oldversion > Not developer issue: > http://bugs.php.net/fix.php?id=20068&r=support > Expected behavior: http://bugs.php.net/fix.php?id=20068&r=notwrong > Not enough info: http://bugs.php.net/fix.php?id=20068&r=notenoughinfo > Submitted twice: http://bugs.php.net/fix.php?id=20068&r=submittedtwice > register_globals: > http://bugs.php.net/fix.php?id=20068&r=globals > PHP 3 support discontinued: > http://bugs.php.net/fix.php?id=20068&r=php3 > Daylight Savings: > http://bugs.php.net/fix.php?id=20068&r=dst > IIS Stability: > http://bugs.php.net/fix.php?id=20068&r=isapi >