PHP类和函数的注释

Question

我想为我的(PHP)类及其函数添加一些文档注释，以某种标准格式编写，以便其他人更容易理解。

请提供一个示例，说明您将如何为以下类和函数编写注释：

关于类的信息：

类名Photos：它有一些与上传照片和显示照片相关的函数。 函数名称是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.
        }

?>

- sunjie

---

这可以帮助吗？http://www.phpdoc.org/ - Nanne

在我看来，该方法不应该包含宽度参数。这些参数很可能表明您的上传函数不仅仅是上传功能（例如还包括重新调整大小等其他功能）。 - Gordon

如果你使用PHPDoc语法，我建议尝试一下DocBlox。它符合PHP 5.3标准，比phpdoc快得多。 - Berry Langerak

你也可以尝试使用https://github.com/theseer/phpdox - Gordon

由于这可能是“PHP注释符”的顶级搜索引擎结果，请参阅官方文档中的“Comments” - “PHP支持'C'，'C ++'和Unix shell风格（Perl风格）的注释。” 我无法想象没有人在Stack Overflow上询问过它（例如，像对于MySQL / SQL）。是否有一个关于它的Stack Overflow问题存在？它们在此问题的答案中被提到，但那并不是主题。 - Peter Mortensen

Answer 1

PHPDocumentor 风格非常标准，大多数 IDE 和文档生成器都能理解。

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

      }
   }

- prodigitalson

---

我认为短描述和所有的描述都是多余的。 - Gordon

在这种情况下，我倾向于同意......但只是一个例子......OP应该查看phpdoc.org上的示例，并查看他使用的其他库如何处理它......我假设CI已将docblocks附加到其内部类？ - prodigitalson

如果这个方法没有返回值怎么办？ - user2957058

默认情况下，它将返回NULL。 - Dan Walker

这个样本非常有帮助。 - undefined

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

这对大多数常见编辑器中的自动完成也很有帮助。

- fatnjazzy

Answer 3

你可以看一下Doxygen。如果你遵循他们的语法，你不仅可以自动生成文档（并不是特别有用），而且Zend StudioIDE会在自动完成时给你代码提示（也就是说，当你开始输入函数名时，它会显示文档）。

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

- satnhak

---

使用 PHP 文档注释，这是唯一被广泛认可并为每个 IDE 所了解的标准。 - NikiC

Doxygen 实现了 phpdoc 标准，而且支持更多的编程语言。 - jocken

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

- SnakE

---

使用PHP文档注释。这是大多数IDE都认可的标准。 - NikiC

使用这种方式会产生大量注释，而且不兼容IDE自动完成功能。 - claudiu.f.marginean

这个模板注释不是标准的，大多数IDE不使用它，而且它可能会对自动完成或使用快捷方式跳转到函数声明等造成问题。 - Nicolas Talichet