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

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

您可能需要查看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.
  }
}

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

PHP类和函数的注释？

4 个答案: