#20066 [Opn->Csd]: [Feature] PHPDoc dependency on *'s

ID: 20066 Updated by: mj@php.net Reported By: mattb@columbia.edu -Status: Open +Status: Closed Bug Type: PEAR related Operating System: GNU/Linux 2.4.18-17.7.x (RedHat) PHP Version: 4.2.3 New Comment: Come one, let's not make a big deal out of this: PHPDoc works the way it currently works and I don't see a reason to change it just because people don't like the documentation style. If you want to contribute a patch which makes PHPDoc also work the way you want, we can discuss about it again. But for now, let's close this report. Previous Comments: ------------------------------------------------------------------------ [2003-02-14 12:22:17] mattb@columbia.edu JavaDoc does *not* do this. JavaDoc ignores the following pattern in its comments (i.e., /** ... */): ^([[:space:]]*\*+)?[[:space:]]* - (or in preg format:) - ^(\s*\*+)?\s* So the following comments will work in JavaDoc (and rightly so) but not in PHPDoc: /** This is a description. */ /** * This is another description. */ /** *******************This is yet another description. */ The *'s are not necessary for JavaDoc to parse the comments correctly. PHPDoc makes them *required* and is very picky about where they should be, which doesn't leave any room for the developer (plus they're just a pain in the butt to type all the time). Like you said, it's a convention, but not a rule. Making it a rule is far too restrictive to be truly useful. Not to mention it's a rule that doesn't have any added benefit to the programmer. ------------------------------------------------------------------------ [2003-02-14 05:00:17] mj@php.net It's just a convention and it's done in Javadoc (where PHPDoc has borrowed most of it's features from) in the same way. ------------------------------------------------------------------------ [2002-10-24 13:27:26] mattb@columbia.edu Not sure if this is the correct forum for reporting PEAR bugs, but here goes... It seems like if the leading ' * 's are missing from the body of a PHPDoc comment, some information will be lost (namely the @... tags). For example, the following comment will not have an author or package: /** This is my class. There are many like it, but this one is mine. @author Me <me@myself.org> @package my_package */ However, this one works fine: /** * This is my class. There are many like it, but this one * is mine. * * @author Me <me@myself.org> * @package my_package */ Is there any reason why the *'s are required? Can the be made to be optional (comments are much easier to edit if they're not forced to be there)? Just my two cents.... ------------------------------------------------------------------------ -- Edit this bug report at http://bugs.php.net/?id=20066&edit=1