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