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
– Gordon, Commented Jul 6, 2011 at 7:41
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. — Berry Langerak
– Berry Langerak, Commented Jul 6, 2011 at 7:43
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. — Peter Mortensen
– Peter Mortensen, Commented Jan 31, 2022 at 15:20

Iman Sedighi · Accepted Answer · 2019-07-17 17:43:01Z

58

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)
      {

      }
   }

edited Jul 17, 2019 at 17:43

Iman Sedighi

8,2875 gold badges52 silver badges55 bronze badges

answered Jul 6, 2011 at 7:37

prodigitalson

60.6k10 gold badges106 silver badges118 bronze badges

Sign up to request clarification or add additional context in comments.

5 Comments

Gordon Over a year ago

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

prodigitalson Over a year ago

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?

user2957058 Over a year ago

What if the method does not return anything?

Dan Walker Over a year ago

Then by default it will return NULL

Anoop P S Over a year ago

this sample is very helpful

Peter Mortensen · Accepted Answer · 2022-02-02 02:00:31Z

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 2, 2022 at 2:00

Peter Mortensen

31.4k22 gold badges110 silver badges134 bronze badges

answered Jul 6, 2011 at 7:37

fatnjazzy

6,14212 gold badges60 silver badges86 bronze badges

Comments

Peter Mortensen · Accepted Answer · 2022-02-02 01:59:40Z

1

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 2, 2022 at 1:59

Peter Mortensen

31.4k22 gold badges110 silver badges134 bronze badges

answered Jul 6, 2011 at 7:34

satnhak

9,9707 gold badges68 silver badges87 bronze badges

2 Comments

NikiC Over a year ago

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

jocken Over a year ago

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

SnakE · Accepted Answer · 2011-07-06 07:41:47Z

-7

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

answered Jul 6, 2011 at 7:41

SnakE

2,5911 gold badge25 silver badges36 bronze badges

3 Comments

NikiC Over a year ago

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

claudiu.f.marginean Over a year ago

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

Nicolas Talichet Over a year ago

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.

Collectives™ on Stack Overflow

Comments for PHP class and functions

4 Answers 4

5 Comments

Comments

2 Comments

3 Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

4 Answers 4

5 Comments

Comments

2 Comments

3 Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related