PHP类和函数的注释？

我想以一些标准格式为我的（PHP）类及其函数添加一些文档注释，以便其他人更容易理解

如果你能给我一个例子，告诉我你将如何为下面的类和函数写评论，我将不胜感激？谢谢

课程信息：

Classname照片：它有一些与上传照片和显示照片相关的功能。函数名是

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

您可能需要查看。如果您遵循它们的语法，不仅可以自动生成文档（实际上没有那么有用），而且Zend IDE将在自动完成时为您提供代码提示（即，当您开始键入函数名时，它将显示文档）

样式非常标准，大多数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)
      {

      }
   }

/**
*照片
* 
* 
*@package-CI
*@子包控制器
*@author你的名字
*/
类照片扩展CI_控制器
{
/**
* 
*上载文件
*
*@param string$文件名说明
*@param string$new_名称说明
*@param integer$new_宽度说明
*@param integer$new_高度说明
*@param string$目录说明
*@返回布尔值
*/
公共函数上传（$file\u name、$new\u name、$new\u width、$new\u height、$directory）
{
}
}

这也将有助于在我将使用的大多数已知编辑器中自动完成。由于人性化的格式，文档注释在代码中易于阅读：

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

这会有帮助吗？在我看来，宽度参数不应该在该方法上。它们是一个强有力的指标，表明你的上传功能不仅仅是上传（例如，它还可以调整大小）。如果你使用PHPDoc语法，我建议你试试。它是PHP5.3兼容的，比phpdoc快得多。你也可以试试我认为简短的描述和所有的描述都是多余的。在这种情况下，我倾向于同意。。。但只是一个例子。。。OP应该在phpdoc.org上查看示例，并看看他使用的其他库是如何做到这一点的。。。我假设CI将docblocks附加到其内部类？如果该方法不返回任何内容怎么办？那么默认情况下，它将使用php doc返回NULL-1。这是大多数IDE都认可的唯一标准。使用它会产生很大的评论，并且与IDEs autocomplete不兼容。此模板评论不标准，IDEs的MOT不使用，不完整，并且可能是自动完成或使用快捷方式转到函数声明等的问题。1使用php文档。这是每个IDE都知道的唯一公认的标准。Doxygen也实现了phpdoc标准+它适用于更多的语言。
 /**
 * 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'){
}

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