Comments for PHP class and functions

Question

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

?>

Solution 1

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

  /**
   * Photos
   * 
   * 
   * @package    CI
   * @subpackage Controller
   * @author     YOUR NAME <[email protected]>
   */
  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)
      {

      }
   }

Solution 2

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

Comments

[Nanne]

This might help? phpdoc.org

[Gordon]

IMO the width arguments shouldnt be on that method. They are a strong indicator that your upload function does more than just uploading (e.g. it also does resizing)

[Berry Langerak]

If you're going with the PHPDoc syntax, I'd recommend giving DocBlox a try. It's PHP 5.3 compliant and much faster than phpdoc.

[Gordon]

You can also try with github.com/theseer/phpdox

[Peter Mortensen]

As this may be the top search engine hit for "PHP comment characters", see Comments (official documentation) - "PHP supports 'C', 'C++' and Unix shell-style (Perl style) comments.". I can't imagine someone not have asked about it on Stack Overflow (e.g., like for MySQL/SQL). Does a Stack Overflow question about it exist somewhere? They are mentioned in an answer to this question, but it isn't the subject.

[Gordon]

I'd argue the short desc and all the descriptions are superfluous.

[prodigitalson]

in this case id tend to agree... but just an example... The OP shoudl check out examples at phpdoc.org as well as look at how other libraries he uses do it... I assume CI has docblocks attached to its internal classes?

[NikiC]

-1 Use php doc. That's the only standard that is recognized by most IDEs.

[NikiC]

-1 Use php doc. That's the only recognized standard that really every IDE knows.

[jocken]

Doxygen implements phpdoc-standards as well + it's for more languages.

[user2957058]

What if the method does not return anything?

[claudiu.f.marginean]

Using this will make big comments and will not be compatible with IDEs autocomplete.

[Dan Walker]

Then by default it will return NULL

[Nicolas Talichet]

This template comment is not standard, not use by mots of IDEs, incomplete and can be a problem for auto completion or to use shortcut to go to a function declaration, etc.