PHP 类和函数的注释

Question

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

您将如何为以下类和函数编写注释的示例是什么？

关于班级的信息：

Classname 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 发布，翻译遵循 CC BY-SA 4.0 许可协议

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 发布，翻译遵循 CC BY-SA 4.0 许可协议

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 发布，翻译遵循 CC BY-SA 4.0 许可协议