CODEWITHSUNDEEP
phpdocumentationphpdoc
FtDRbwLXw6
FtDRbwLXw6

Reputation: 28891

Proper way to denote array data type for phpDocumentor?

Which of the following is the proper way to document the return type of this method for phpDocumentor?

Method 1:

/**
 * @return array Foo array.
 */
public function foo() {
    return array(1, 2, 3);
}

Method 2:

/**
 * @return integer[] Foo array.
 */
public function foo() {
    return array(1, 2, 3);
}

Also, are there any IDE implications from either method?

Edit:

It appears that both PhpStorm and Netbeans 7.1+ IDEs support the 2nd method.

Upvotes: 10

Views: 4540

Answers (2)

emegeve
emegeve

Reputation: 81

At the moment of writing this answer, these are the accepted ways of phpDocumentor (and probably other PHPDoc implementations) to denote an array:

  1. unspecified, no definition of the contents of the represented array is given. Example: @return array

  2. specified containing a single type, the Type definition informs the reader of the type of each array element. Only one Type is then expected as element for a given array. Example: @return int[]

    Please note that mixed is also a single type and with this keyword it is possible to indicate that each array element contains any possible type.

  3. specified containing multiple types, the Type definition informs the reader of the type of each array element. Each element can be of any of the given types. Example: @return (int|string)[]

Upvotes: 8

Evert
Evert

Reputation: 99523

Both methods are technically correct, but this one is considered 'better' because it's more specific (int and integer are interchangeable):

@return int[]

Documented here:

http://www.phpdoc.org/docs/latest/guides/types.html

Upvotes: 18

Related Questions