phpDoc - no parameters or return value

Question

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;
}

score 1 · Accepted Answer · edited May 23 '17 at 10:26

1

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

edited May 23 '17 at 10:26

Community

1
1

answered Oct 23 '14 at 17:57

chiliNUT

18,989
14
66
106

This is true, and something that I forgot to mention in the OP. Let's say in this instance that I'm not including a description; the contents of the docblock will be empty. What's the normal way to handle that? – Joe Oct 24 '14 at 08:13
Explicitly showing `@return void` tells your user "expect no return value, so make no assumptions about one". Having no return tag at all tells your user "assume that no no return value is given". It's functionally all the same at the end of the day... it really depends on how explicit you prefer to be for your reader. I always include `@return void` in mine, because I dislike assumptions ;-) – ashnazg Oct 24 '14 at 14:26
to quote the wiki **@return|This tag should not be used for constructors or methods defined with a void return type.** – chiliNUT Oct 24 '14 at 15:39

score 0 · Answer 2 · answered Oct 23 '14 at 17:47

0

Your choice phpDoc will recognize a function in each case. But maybe you want to return the string and build your response string outside the class.

answered Oct 23 '14 at 17:47

Jens W

188
6

Returning the string won't always work. For example, I've got a script that outputs the contents of a large file. I didn't realise how large that file would get and it made the script run out of memory when I returned it from a function. Switched to readfile instead which doesn't use anywhere near as much memory. – Gnuffo1 Jun 18 '15 at 15:55

phpDoc - no parameters or return value

2 Answers2