What is the preferred way of notating methods in comments?

Question

Hey!

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!

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

Answer 2

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

Answer 3

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.

Answer 4

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.