Search code examples
phpphpdocdocblocks

phpDoc - no parameters or return value


Say I have the following class stub:

class Gentleman {

    /** @var string */
    protected $guestsName;

    /**
     * @param string $name The name of our esteemed guest
     */
    public function __construct($name) {
        $this->guestsName = $name;
    }

    public function beCourteous() {
        echo 'Salutations, dear ' . $this->guestsName;
    }

}

The beCourteous() method doesn't actually take any input, or produce any return values. What is the correct phpDoc block?

public function beCourteous() {
    // No docblock
    echo 'Salutations, dear ' . $this->guestsName;
}

/**
 *
 */
public function beCourteous() {
    // One blank line
    echo 'Salutations, dear ' . $this->guestsName;
}

/**
 */
public function beCourteous() {
    // No blank lines
    echo 'Salutations, dear ' . $this->guestsName;
}

Solution

  • A function which accepts no parameters nor returns a value should not have @param or @return in the doc comment. However, you can (and should) still include a description

    /**
     * Echos a salutation to <code>$this->guestsName</code>
     */
    public function beCourteous() {
        echo 'Salutations, dear ' . $this->guestsName;
    }
    

    See here: (Related, not exactly a dupe) PHPDoc: @return void necessary?

    And here: http://en.wikipedia.org/wiki/PHPDoc