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

?>

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) — Gordon, Jul 06 '11 at 07:41
If you're going with the PHPDoc syntax, I'd recommend giving [DocBlox](http://www.docblox-project.org) a try. It's PHP 5.3 compliant and much faster than phpdoc. — Berry Langerak, Jul 06 '11 at 07:43
As this may be the top search engine hit for *"PHP comment characters"*, see *[Comments](https://www.php.net/manual/en/language.basic-syntax.comments.php)* (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](https://stackoverflow.com/questions/9098655)). Does a Stack Overflow question about it exist somewhere? They are mentioned in an answer [to this question](https://stackoverflow.com/q/3462103/), but it isn't the subject. — Peter Mortensen, Jan 31 '22 at 15:20

score 54 · Accepted Answer · edited Jul 17 '19 at 17:43

54

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

  /**
   * Photos
   * 
   * 
   * @package    CI
   * @subpackage Controller
   * @author     YOUR NAME <YOUREMAIL@domain.com>
   */
  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)
      {

      }
   }

edited Jul 17 '19 at 17:43

Iman Sedighi

7,624
4
48
55

answered Jul 06 '11 at 07:37

prodigitalson

60,050
10
100
114

1

I'd argue the short desc and all the descriptions are superfluous. – Gordon Jul 06 '11 at 07:40
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? – prodigitalson Jul 06 '11 at 07:45
What if the method does not return anything? – user2957058 Aug 08 '16 at 21:09
Then by default it will return NULL – Dan Walker Feb 07 '17 at 13:07

score 2 · Answer 2 · edited Feb 02 '22 at 02:00

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.

edited Feb 02 '22 at 02:00

Peter Mortensen

30,738
21
105
131

answered Jul 06 '11 at 07:37

fatnjazzy

6,070
12
57
83

score 0 · Answer 3 · edited Feb 02 '22 at 01:59

0

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

edited Feb 02 '22 at 01:59

Peter Mortensen

30,738
21
105
131

answered Jul 06 '11 at 07:34

satnhak

9,407
5
63
81

6

-1 Use php doc. That's the only recognized standard that really every IDE knows. – NikiC Jul 06 '11 at 08:20
2

Doxygen implements phpdoc-standards as well + it's for more languages. – jocken Sep 04 '12 at 13:32

score -7 · Answer 4 · answered Jul 06 '11 at 07:41

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

<?php

/*
    Class: Photos

    Some functions related to uploading the photo and displaying the photos.
*/
class Photos extends CI_Controller
{
    /*
        Function: upload

        Upload a photo to the server so that you can later <display> it.

        Arguments:

            file_name - name of the file
            new_name  - name of the file on the server
            new_width - resize to this before uploading
            new_height - resize to this before uploading

        Returns:

            true or false.

        See Also:

            <display>
            <delete>
    */            
    public function upload($file_name, $new_name, $new_width, new_$height, $directory)
    {
        ...
        ...
        returns true or false.
    }

-1 Use php doc. That's the only standard that is recognized by most IDEs. — NikiC, Jul 06 '11 at 08:19
Using this will make big comments and will not be compatible with IDEs autocomplete. — claudiu.f.marginean, Dec 21 '16 at 10:06
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. — Nicolas Talichet, Jun 29 '18 at 03:10

Comments for PHP class and functions

4 Answers4