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

Question

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

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

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

Имя класса Фотографии: в нем есть некоторые функции, связанные с загрузкой фотографии и отображением фотографий.имена функций: 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.
    }

Answer 1

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

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

      }
   }

Answer 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'){
}

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

Answer 3

Я бы использовал 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.
    }

Answer 4

Возможно, вы захотите посмотреть на 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.
  }
}