3

そのため、フォルダー PayPal には、API を使用するための複数のクラスがあります。

すべてのクラスを順番に使用する方法についてのドキュメントを作成したいと考えています。ここに私の質問があります：

  1. それらのパッケージを作成するにはどうすればよいですか? 上記の各クラスの原因は、phpdoc タグ @package PayPal を使用したことです。PHPのパッケージは単なるフォルダーですか?

  2. パッケージのドキュメントはどこに置くのですか? これにはベストプラクティスがありますか? ...という名前のフォルダー内のファイル？

  3. クラスまたはパッケージ固有の例の配置方法。ステップ 1 ブラ ブラ、ステップ 2 ブラ ブラ? ありがとう！

4

1 に答える 1

4

複数のクラスに同じパッケージ アノテーションを別々のファイルに含めることができます。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 
 */
于 2010-04-07T11:26:27.683 に答える