How do you comment out a class in php?

I would like to add some documentation comments for my [PHP] class and its functions in some standard format, so that it’s easier for others to understand.

What would an example of how you would write comments for the following class and function?

Information about the class:

Classname Photos: it has some functions related to uploading the photo and displaying the photos. Function names are upload[], display[], delete[].

Information about the upload function:

Uploads the resizes and uploads the image and has few parameters as shown below.

asked Jul 6, 2011 at 7:31

5

PHPDocumentor style is pretty standard and understood by most IDE's and documentation generators.

  /**
   * Photos
   * 
   * 
   * @package    CI
   * @subpackage Controller
   * @author     YOUR NAME 
   */
  class Photos extends CI_Controller
  {

      /**
       * 
       * Uploads a file
       *
       * @param string $file_name  description
       * @param string $new_name  description
       * @param integer $new_width  description
       * @param integer $new_height  description
       * @param string $directory  description
       * @return boolean
       */
      public function upload[$file_name, $new_name, $new_width, $new_height, $directory]
      {

      }
   }

Iman Sedighi

7,1064 gold badges48 silver badges53 bronze badges

answered Jul 6, 2011 at 7:37

prodigitalsonprodigitalson

59.5k9 gold badges97 silver badges112 bronze badges

4

 /**
 * A sample function docblock
 * @global string document the fact that this function uses $_myvar
 * @staticvar integer $staticvar this is actually what is returned
 * @param string $param1 name to declare
 * @param string $param2 value of the name
 * @return integer
 */
function firstFunc[$param1, $param2 = 'optional']{
}

This will also be helpful for auto-complete in most known editors.

answered Jul 6, 2011 at 7:37

fatnjazzyfatnjazzy

5,92012 gold badges55 silver badges82 bronze badges

You might want to look at Doxygen. If you follow their syntax not only will you be able to auto generate documentation [not actually so useful], but the Zend Studio IDE will give you code hints on auto completion [i.e., it will display the documentation when you start to type the function name].

/*! \brief My Photo Class
 *  Does some stuff with photos
 */
class Photos extends CI_Controller
{
  /*! \brief Uploads a file
   *  \param $file_name The name of the file
   *  ...
   *  \returns A value indicating success
   */
  public function upload[$file_name, $new_name, $new_width, new_$height, $directory]
  {
    ...
    ...
    returns true or false.
  }
}

answered Jul 6, 2011 at 7:34

satnhaksatnhak

9,0105 gold badges62 silver badges78 bronze badges

2

I would use Natural Docs. The doc comments are easy to read right in the code thanks to human-friendly formatting: