Комментарии для PHP-класса и функций?

Я хотел бы добавить некоторые комментарии к документации для моего (PHP) класса и его функций в некотором стандартном формате, чтобы его было легче понять другим.

Я буду appriciate, если вы можете дать мне пример того, как вы будете писать комментарии для следующих классов и функций? Спасибо.

Информация о классе:

Имя класса Фотографии: у него есть некоторые функции, связанные с загрузкой фотографии и отображением фотографий. имена функций upload(), display(), delete().

Информация о функции загрузки:

загружает изменения и загружает изображение и имеет несколько параметров, как показано ниже.

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

Ответ 1

Стиль PHPDocumentor довольно стандартный и понятен большинству IDE и генераторов документации.

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

      }
   }

Ответ 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'){
}

Это также будет полезно для автозаполнения в большинстве известных редакторов

Ответ 3

Вы можете посмотреть на Doxygen. Если вы будете следовать их синтаксису, вы не только сможете автоматически генерировать документацию (на самом деле не очень полезно), но Zend IDE даст вам подсказки кода по автозаполнению (то есть отобразит документацию, когда вы начнете вводить имя функции),

/*! \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.
  }
}

Ответ 4

Я бы использовал Natural Docs. Комментарии к документу легко читаются в коде благодаря удобному для пользователя форматированию:

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