phpstringphpdoc

How to document available options for string parameter


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

Solution

  • 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 :)