'Comments for PHP class and functions

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.

<?php
    class Photos extends CI_Controller
    {
        public function upload($file_name, $new_name, $new_width, $new_height, $directory)
        {
            ...
            ...
            returns true or false.
        }

?>
phpsyntaxcommentsstandards


Solution 1:[1]

 /**
 * 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.

Solution 2:[2]

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

Sources

This article follows the attribution requirements of Stack Overflow and is licensed under CC BY-SA 3.0.

Source: Stack Overflow

Solution Source
Solution 1 Peter Mortensen
Solution 2 Peter Mortensen

Related Questions