php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login

go to bug id or search bugs for

Bug #20066 [Feature] PHPDoc dependency on *'s
Submitted: 2002-10-24 13:27 UTC Modified: 2003-02-15 02:03 UTC
Votes:1
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
View Developer Edit
Welcome! If you don't have a Git account, you can't do anything here.
If you reported this bug, you can edit this bug over here.
(description)
Block user comment
Status: Assign to:
Package:
Bug Type:
Summary:
From: mattb at columbia dot edu
New email:
PHP Version: OS:

 

 [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 <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....

Patches

Pull Requests

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2003-02-14 05:00 UTC] 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.
 [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., /** ... */):

^([[: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-15 02:03 UTC] mj@php.net 
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-2025 The PHP Group
All rights reserved. 		Last updated: Fri May 09 17:01:28 2025 UTC