phpDocumentor
v3.5.3
phpDocumentor は、PHP プロジェクトの事実上のドキュメント ツールとして機能し、包括的なドキュメントを簡単に生成するための堅牢なソリューションを提供します。 phpDocumentor は、PHP ソース コードと DocBlock コメントを分析することにより、API ドキュメントの完全なセットを生成し、明確で十分にドキュメント化されたコードベースを目指す開発者にとって不可欠なツールとなります。
phpDocumentor は API ドキュメントの優れた機能を超えて、追加機能を提供します。 UML 図を作成する機能が備わっており、コード構造を視覚化するための多用途ツールになります。さらに、phpDocumentor は、RestructurdText と Markdown 構文の両方をサポートする、フル機能のマークアップ言語パーサーを提供します。この柔軟性により、好みに最も適したマークアップ言語を使用してプロジェクトを文書化できます。
phpDocumentor の注目すべき機能は、API ドキュメントの一部を RestructedText ドキュメントに直接組み込む機能です。この統合により、ドキュメントとコードの同期が確保され、正確で最新のプロジェクト ドキュメントを維持するための時間と労力が節約されます。
phpDocumentor は、前身である phpDocumentor 1 と JavaDoc からインスピレーションを受け、革新を続け、最新のテクノロジーと PHP 言語機能を常に最新の状態に保ちます。この取り組みにより、開発者は最新の開発慣行に合わせて可能な限り最高のドキュメント エクスペリエンスにアクセスできるようになります。
このガイドでは、API ドキュメントを生成するコア機能からマークアップ言語を解析する高度な機能まで、phpDocumentor のさまざまな機能について説明します。初心者でも経験豊富な開発者でも、phpDocumentor は、十分に文書化され、保守しやすく、わかりやすい PHP プロジェクトを作成するための味方です。
v3 は最新の安定版リリースです。
詳細については、https://docs.phpdoc.org/ でオンライン ドキュメントを確認してください。
phpDocumentor は以下をサポートします。
PHP 7.0 以降と互換性があり、ネームスペース、クロージャなどの完全なサポートが提供されます。
型よりも docblock を使用すると、ネイティブ php ですべての形式がサポートされているわけではない型について、docblock をより明示的に指定できます。
任意のタグを表示します。一部のタグは phpDocumentor に追加機能を追加します (@link など)。
メモリ使用量が低く、小規模プロジェクトのピーク時のメモリ使用量は 20MB 未満、中規模プロジェクトの場合は 40MB、大規模なフレームワークの場合は 100MB です。
インクリメンタル解析。前回の実行時の構造ファイルを保持している場合、上記の処理速度の向上に加えて、パフォーマンスがさらに最大 80% 向上します。
簡単なテンプレートの構築。ブランディングを作成したい場合は、1 つのタスクを呼び出して 3 つのファイルを編集するだけです。
2 段階のプロセス。phpDocumentor は、出力を作成する前に、まずアプリケーション構造を使用してキャッシュを生成します。必要に応じて、それを使用して独自のツールやフォーマッタを強化することもできます。
ジェネリックスのサポート、PHP タイプの静的分析の増加により、より複雑になりました。 phpDocumentor はこれらの型を理解します。そして、それらをファーストクラスのタイプとしてレンダリングします。
PhpDocumentor を実行するには PHP 8.1 以降が必要です。ただし、以前の PHP バージョンのコードは分析できます。
phpDocumentor で提供されるすべてのテンプレートは、読み取りコード ベースに基づいたクラス図をサポートしています。これには、phpDocumentor を実行しているマシンにアプリケーション [PlantUml] をインストールする必要があります。 [PlantUml] を使用したクラス図のレンダリングはオプションであり、[PlantUml] が欠落していることに関する警告は無視できます。ただし、この場合、ドキュメントにはいくつかのデッドリンクが含まれます。クラス図はオプション--setting=graphs.enabled=trueを使用して作成されます。
phpDocumentor をインストールするには 4 つの方法があります。
phive の使用 (推奨)
PHAR の使用 (手動インストール)
ドッカー経由
作曲家経由
$ phive install phpDocumentor --trust-gpg-keys 8AC0BAA79732DD42
phive の詳細については、ウェブサイトをご覧ください。これで phpDocumentor がインストールされたので、次のように実行できます。
php tools/phpDocumentor
https://github.com/phpDocumentor/phpDocumentor/releases から phar ファイルをダウンロードします。
次のように phar を実行できます: php phpDocumentor.phar
$ docker pull phpdoc/phpdoc
$ docker run --rm -v $(pwd):/data phpdoc/phpdoc
でも待ってください？作曲家はどうですか？
ああ、あなたは私たちの秘密を発見しましたね。 phpDocumentor のインストールに使用できる phpdocumentor コンポーザー パッケージがあります。
ただし、phpDocumentor は複雑なアプリケーションであり、そのライブラリは他の無数のライブラリやアプリケーションで使用されています (うち 2 つのライブラリはそれぞれ 1 億 5,000 万以上ダウンロードされています)。これは、私たちの依存関係の 1 つとあなたの依存関係の間で競合が発生する可能性が高いことを意味します。そして高いと言ったら本当に高いです。
したがって、上記の理由により、私たちは Composer を使用した phpDocumentor のインストールを推奨したり、積極的にサポートしたりしません。
phpDocumentor を実行する最も簡単な方法は、次のコマンドを実行することです。
$ phpdoc run -d <SOURCE_DIRECTORY> -t <TARGET_DIRECTORY>
このコマンドは、 -d引数を使用して提供されたソース コードを解析し、 -t引数で指定されたフォルダーに出力します。
phpDocumentor は、ドキュメントの出力を構成するための幅広いオプションをサポートしています。次のコマンドを実行するか、Web サイトで利用可能なコマンドライン オプションの詳細なリストを確認してください。
$ phpdoc run -h
phpDocumentor は、設定ファイル (デフォルトでは phpdoc.xml または phpdoc.dist.xml という名前) の使用もサポートしています。形式とサポートされているオプションを確認するには、ドキュメントを参照してください。
PhpDocumentor には夜間リリースがありません。ただし、各パイプライン中に phar アーティファクトが構築されます。 phpDocumentor の最先端バージョンをテストしたい場合は、このリポジトリのアクション セクションをご覧ください。成功した各 QA ワークフローには、phar アーティファクトが構築された [アーティファクト] セクションが下部にあります。
弊社へのご連絡は以下の方法で簡単に行えます。
Twitter: @phpDocumentor
ウェブサイト: https://www.phpdoc.org
GitHub: https://www.github.com/phpDocumentor/phpDocumentor
電子メール: [email protected]
