phpDocumentor How to document available options fo

问题:

I have a public method for a class and I would like to document the available string values that the method can accept. Would this be acceptable:

/**
* Set size of photos
* 
* @param string $size can be one of these options: url_sq, url_t, url_s, url_m, url_o
* @return void
*/
public function setSize($size){
    $this->_size = $size;
}

回答1:

Yes, it's acceptable, but you can do it smarter:

class TheClass
{
 const photo_size_sq = 'url_sq';
 const photo_size_tiny = 'url_t';
 const photo_size_small = 'url_s';
 const photo_size_m = 'url_m';
 const photo_size_o = 'url_o';

/**
* Set size of photos
* 
* @param string $size see photo_size_* constants
* @return void
*/
public function setSize($size){
    $this->_size = $size;
}
}

So when you will call this function, you can use IDE's autocompletion, to not keep in memory all values and to be sure that your code typed correct, without typos:

$object->setSize($object::photo_size_small);

Of course, names of constants can be more short and more descriptive, when you are author of the code :)