phpdoc - Specifying return value in annotation in PHP

Question

Let's say I expect my function to return either null or the array. Is this ok if I add array possible values?

/**
 * @return null|array{
 *     md5: ?string,
 *     data?: array,
 *     size?: ?string,
 *     bit_rate?: ?string,
 *     remote?: ?string,
 *     url?: ?string,
 *     body?: ?string,
 *     refresh?: bool,
 *     refreshRate?: int,
 *     data?: array{
 *         playlist?: array,
 *         repeat?: array,
 *         width?: int,
 *         height?: int,
 *         compression?: mixed,
 *         depth?: int,
 *         alpha_channel?: int,
 *         orientation?: string,
 *         url?: string,
 *     }
 * }
 */

Answer 1

There is an issue on github, describing this problem. issue

Some code using that feature:

/**
 * @return null|array{
 *     md5: ?string,
 *     data?: array,
 *     size?: ?string,
 *     bit_rate?: ?string,
 *     remote?: ?string("remote", "local"), // documents possible return values
 *     url?: ?string,
 *     body?: ?string,
 *     refresh?: bool,
 *     refreshRate?: int,
 *     data?: array{
 *         playlist?: array,
 *         repeat?: array,
 *         width?: int,
 *         height?: int,
 *         compression?: mixed,
 *         depth?: int,
 *         alpha_channel?: int,
 *         orientation?: string,
 *         url?: string,
 *     }
 * }
 */
function getInfo(): ?array {
    return [
        'md5' => md5('some info'),
        'url' => 'https://example.com/something',
        'data' => [],
        'remote' => 'remote' // possible values `remote` or `local`
    ];
}

I think the best option is to document array in the function description:

/**
 * Returns information about audio source
 *
 * Returns
 * array['md5']            null|string  md5 hash of something
 * array['size']?          null|string  size of audio (should be numeric)
 * array['bit_rate']?      null|string  bit rate
 * array['remote']?        null|string  is it a remote source possible values: "remote", "local" (should be bool)
 * array['url']?           null|string  remote url
 * array['body']           null|string  stream body
 * array['refresh']?       bool         some option
 * array['refreshRate']    int          refresh rate
 * array['data']?          array        audio data
 *      ['playlist']?      array        some playlist data
 *      ['repeat']?        array        some repeat data
 *      ['width']?         int          width of something
 *      ['height']?        int          height of something
 *      ['compression']?   mixed        some compression data
 *      ['delth']?         int          depth value
 *      ['alpha_channel']? int          alpha channel value
 *      ['orientation']?   string       some orientation data
 *      ['url']?           string       url of something
 *
 * @return null|array see above
 */