Zend框架代码文档样式

我想知道为什么有两块评论与重复的信息。有人知道答案吗？Zend框架代码文档样式

/** 
* 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 [email protected] 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。那些在第一个和第二个评论块上重复两次。

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

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

来源

2012-02-16 Keyne Viana

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

你注意到的行为是如何phpDocumentator读取文件并解析它，有两种方法@package标签可以被解析：

页面级封装（定义，功能，包括）
类级封装（类，变量，方法）

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

为了实现一个很好的文档，一个很好的资源是the phpDoc official manual。

来源

2012-02-16 03:02:32 Liyali

谢谢你Liyali。我对phpdoc工具的认识很差。到目前为止，我刚刚通过IDE评论了我的代码，但不是从它的工具。我会看看并弄清楚。 – 2012-02-16 10:13:58

更多这两个docblocks的这种做法的起源 - phpDocumentor _requires_一个文件级docblock和一个级别的docblock。如果它找不到它们，它不会崩溃，但它会在运行时创建的errors.html文件中将这个缺失项目列为“错误”。 – ashnazg 2012-02-16 22:07:40

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

来源

2012-02-16 02:15:18 JRL

这似乎很合理。但是我想知道为什么会这样，因为通常第二个注释块不包含其他重复变量（除此之外我还没有看到任何类）。 – 2012-02-16 02:21:50

这是不正确的，@liyali有正确的答案。 – vascowhite 2012-02-16 08:45:54

Zend框架代码文档样式

回答

相关问题