所以在 PayPal 文件夹中,我有多个类用于使用他们的 API。
我想制作有关如何按顺序使用所有类的文档。所以这是我的问题:
我如何为他们创建一个包?因为在每个类上面我都使用了 phpdoc 标签@package PayPal。php中的包只是一个文件夹吗?
我在哪里放置包的文档?有这方面的最佳做法吗?文件夹中名为...的文件?
如何放置特定于类或包的示例,例如。第 1 步 bla bla,第 2 步 bla bla?谢谢!
您可以在不同的文件中为多个类使用相同的包注释。PHP Documentor 将收集它们,并在创建 API 文档时使用相同的包注释对文件进行分组。
例如http://framework.zend.com/svn/framework/standard/trunk/library/Zend/Validate.php
/**
* @category Zend
* @package Zend_Validate
* @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
*/
class Zend_Validate implements Zend_Validate_Interface
和http://framework.zend.com/svn/framework/standard/trunk/library/Zend/Validate/Alnum.php
/**
* @category Zend
* @package Zend_Validate
* @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
*/
class Zend_Validate_Alnum extends Zend_Validate_Abstract
两者都是单独的文件,但属于 Zend_Validate 包。因此,在http://framework.zend.com/apidoc/core/上,您可以找到它们分组在同一个包中。
您还可以使用子包将其他类分组到普通包之下。例如http://framework.zend.com/svn/framework/standard/trunk/library/Zend/Validate/Sitemap/Lastmod.php
/**
* Validates whether a given value is valid as a sitemap <lastmod> value
*
* @link http://www.sitemaps.org/protocol.php Sitemaps XML format
*
* @category Zend
* @package Zend_Validate
* @subpackage Sitemap
* @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
*/
class Zend_Validate_Sitemap_Lastmod extends Zend_Validate_Abstract
请参阅上面链接的 API 文档以了解它在生成时的显示方式。
您不记录包注释。注释仅用于在逻辑上对概念上属于的类或文件进行分组。如果您想要一个包描述,请将其写入包的最合适的文件中,或者创建一个单独的文件并为其提供与该包中其他文件/类相同的注释。
对于包的使用示例,您可以使用示例注释来链接包含示例的文件,或者简单地将它们与 DocBlocks 中的代码标记内联。如果您使用单独的文件来记录您的包,您可以将它们插入那里。
/**
* MyLib
*
* Files under the MyLib package do foo and bar. They are baz.
*
* Usage Examples of MyLib classes
* <code>
* $foo = new Foo;
* $foo->doSomething()
* </code>
*
* @package MyLib
*
* @example /some/path/to/an/example/file
*/