Zend Framework 代码文档风格 [关闭]

Question

我想知道为什么有两个具有重复信息的 cmets 块。有人知道答案吗？

/**
 * Zend Framework
 *
 * LICENSE
 *
 * This source file is subject to the new BSD license that is bundled
 * with this package in the file LICENSE.txt.
 * It is also available through the world-wide-web at this URL:
 * http://framework.zend.com/license/new-bsd
 * If you did not receive a copy of the license and are unable to
 * obtain it through the world-wide-web, please send an email
 * to license@zend.com so we can send you a copy immediately.
 *
 * @category   Zend
 * @package    Zend_Controller
 * @copyright  Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 * @version    $Id: Action.php 23775 2011-03-01 17:25:24Z ralph $
 */

/**
 * @see Zend_Controller_Action_HelperBroker
 */
require_once 'Zend/Controller/Action/HelperBroker.php';

/**
 * @see Zend_Controller_Action_Interface
 */
require_once 'Zend/Controller/Action/Interface.php';

/**
 * @see Zend_Controller_Front
 */
require_once 'Zend/Controller/Front.php';

/**
 * @category   Zend
 * @package    Zend_Controller
 * @copyright  Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */
abstract class Zend_Controller_Action implements Zend_Controller_Action_Interface
{

例如：@category、@package、@copyright、@license。这些在第一个和第二个评论块上重复两次。

我一直在寻找评论最佳实践，在分析他们的代码时，我想出了这个问题。

如果太简单了，请不要怪我。

Answer 1

Zend Framework 使用 phpDocumentator 来呈现他们的技术文档。

您注意到的行为是 phpDocumentator 如何读取文件并对其进行解析，@package 标签可以通过两种方式进行解析：

• 页面级包（定义、函数、包含）
• 类级包（类、变量、方法）

@license 和@copyright 页面可以关联到任何元素（包括、页面、定义、方法、变量等）

the phpDoc official manual 是实现出色文档的好资源。

Answer 2

我不知道这一点，但我认为这是因为他们有一个单独的预定义模板，用于 PHP 文件顶部的内容和类上方的文档块。在还包含类的文件中，您会发现这种重复。