|  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Bug #20066 [Feature] PHPDoc dependency on *'s
Submitted: 2002-10-24 13:27 UTC Modified: 2003-02-15 02:03 UTC
Avg. Score:3.0 ± 0.0
Reproduced:1 of 1 (100.0%)
Same Version:0 (0.0%)
Same OS:1 (100.0%)
From: mattb at columbia dot edu Assigned:
Status: Closed Package: PEAR related
PHP Version: 4.2.3 OS: GNU/Linux 2.4.18-17.7.x (RedHat)
Private report: No CVE-ID: None
 [2002-10-24 13:27 UTC] mattb at columbia dot 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 <>
     @package my_package

However, this one works fine:

   * This is my class. There are many like it, but this one 
   * is mine.
   * @author Me <>
   * @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....


Add a Patch

Pull Requests

Add a Pull Request


AllCommentsChangesGit/SVN commitsRelated reports
 [2003-02-14 05:00 UTC]
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.
 [2003-02-14 12:22 UTC] mattb at columbia dot edu
JavaDoc does *not* do this. JavaDoc ignores the following pattern in its comments (i.e., /** ... */):

    - (or in preg format:) -

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-15 02:03 UTC]
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.
PHP Copyright © 2001-2021 The PHP Group
All rights reserved.
Last updated: Mon Aug 02 18:01:24 2021 UTC