What is the preferred way of notating methods in comments?

Question

Sometimes one has to refer to another method when commenting. Here some example in PHP:

class A
{
    /**
     * @see B::bar
     */
    public function foo()
    {
        B::bar();
    }
}

class B
{
    public static function bar()
    {
        // ...
    }
}

So what if there would be a non-static method bar in class B? What is the best way to name other methods in comments?

Edit

The PHP manual seems to use mysqli->affected_rows as well as PDO::beginTransaction. But what it does not is including the parentheses after the method's name. What is pro and con here? I mean it is quite obvious that a method is followed by parentheses, so why no leave 'em out?

Thx in advance!

score 1 · Answer 1 · answered Jun 11 '09 at 17:00

1

I would write:

class A {
    // see B::bar()
    public function foo() {
        B::bar();
    }
}

My most strongly held opinion concerning my various changes is that letterbox comments are the work of the Devil. Regarding your static vs. non-static thing, I understand and use B::bar() to refer to the function definition for conversational purposes, whether or not bar() is static.

The above example is, of course, for illustrative purposes only, because if there were actually a function A::foo() that did nothing but call B::bar(), I would not include the comment, because if the person reading my code is an idiot, I do not wish to help him.

answered Jun 11 '09 at 17:00

chaos

122,029
33
303
309

1. Thx! 2. Sorry for asking but I'm no native speaker. What is a "letterbox comment"? – Philippe Gerber Jun 11 '09 at 17:50
By letterbox comments I mean the ones where you use /* */ and have that left border of * characters. The really egregious ones have massive top and bottom borders of asterisks (sometimes even right borders, if you can believe it). I hate the normal ones, like you have in your example, largely because they remind me of the egregious ones. – chaos Jun 11 '09 at 18:03
1

The DocBlock comments are not a personal coding style issue, but the format that phpDocumentor understands. It's functional purpose is much like Perl's Pod and a good standard to follow. Unfortunately, it may offend some programmers' personal coding style, as chaos has noted. However, phpDoc DockBlocks are required in the PEAR and Zend coding style guides & every programmer following a standard has to make a few concessions to their own style, at times. See: http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics – racerror Jun 12 '09 at 19:48

score 1 · Accepted Answer · edited Nov 13 '11 at 18:02

1

You could use the -> operator to reference an instance/object method rather than a class method. PHP.net does that in their manual as well (see MySQLi class for example).

edited Nov 13 '11 at 18:02

NullUserException

83,810
28
209
234

answered Jun 11 '09 at 17:01

Gumbo

643,351
109
780
844

Thx! But even the official PHP documentation isn't consistent. Eg. http://docs.php.net/manual/en/book.pdo.php uses `::` :/ – Philippe Gerber Jun 11 '09 at 17:47
1

I am shocked, shocked I tell you to hear of inconsistencies within PHP ;) – Dominic Rodger Jun 11 '09 at 18:08

score 1 · Answer 3 · answered Jun 11 '09 at 18:12

In my opinion, your example is sufficient. You should refer to B::bar as B::bar(), though.

You might want to consider using the @uses php-doc tag, which will automatically create a @usedby reference in documentation generated for B::bar(), pointing back to class A.

/**
 * @uses B::bar()
 */

As far as documentation is concerned, the method being static is not relevant to @uses, @usedby or @see, only @static. The static notation in the @uses tag simply communicates the scope to look for the bar() method in, not to denote @static.

score 0 · Answer 4 · answered Jun 11 '09 at 18:36

The documentation for phpDocumentor seems to imply that you could use something like

class A
{
  /**
   * @see B
   * @see function bar()
   */
  public function foo()
  {
    // ...
  }
}

Also from the phpDocumentor manual:

@uses is very similar to @see, see the documentation for @see for details on format and structure. The @uses tag differs from @see in two ways. @see is a one-way link, meaning the documentation containing a @see tag contains a link to other documentation. The @uses tag automatically creates a virtual @usedby tag in the other documentation that links to the documentation containing the @uses tag. In other words, it is exactly like @see, except a return link is added automatically.

What is the preferred way of notating methods in comments?

4 Answers4