#20068 [Opn->WFx]: PHPDoc short line is confusing

ID: 20068 Updated by: jellybob@php.net Reported By: mattb at columbia dot edu -Status: Open +Status: Wont fix Bug Type: PEAR related Operating System: GNU/Linux 2.4.18-17.7.x (RedHat) PHP Version: 4.2.3 New Comment: PHPDoc is no longer supported, please use PHPDocumentor instead (see http://pear.php.net/package-info.php?package=PhpDocumentor and http://phpdocu.sourceforge.net/ for more details.) Previous Comments: ------------------------------------------------------------------------ [2002-10-24 13:34:46] mattb at columbia dot edu 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 this bug report at http://bugs.php.net/?id=20068&edit=1