php - php 包的文档？

Question

所以在文件夹 PayPal 中我有多个使用他们的 API 的类。

我想制作一份文档，说明如何按顺序使用所有类。所以这是我的问题:

1. 我如何为他们创建一个包？因为在每个类上面我都使用了 phpdoc 标签@package PayPal。 php中的包只是一个文件夹吗？

2. 我应该把包的文档放在哪里？有这方面的最佳做法吗？名为 ... 的文件夹中的文件？

3. 如何放置特定于类或包的示例，例如。第 1 步 bla bla，第 2 步 bla bla？ 谢谢!

Answer 1

您可以在单独的文件中为多个类使用相同的包注释。 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 文档，了解它在生成时如何显示。

您不记录包注释。注释仅用于在逻辑上将概念上属于一起的类或文件分组。如果您想要一个包描述，请将其写入包中最合适的文件或创建一个单独的文件并为其提供与该包中的其他文件/类相同的注释。

对于包的使用示例，您可以使用示例注释链接包含示例的文件，或者简单地将它们与 DocBlock 中的代码标记内联。如果您使用单独的文件来记录您的包，您可以将它们插入那里。

/**
 * 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 
 */