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 Add Comment Developer Edit
Anyone can comment on a bug. Have a simpler test case? Does it work for you on a different platform? Let us know!
Just going to say 'Me too!'? Don't clutter the database with that please !
Your email address:
MUST BE VALID
Solve the problem:
41 + 20 = ?
Subscribe to this entry?

 
 [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

Add a Patch

Pull Requests

Add a Pull Request

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-2024 The PHP Group
All rights reserved. 		Last updated: Fri Apr 26 07:01:32 2024 UTC