PHP関数とクラスをインラインでどのように文書化しますか?

2009年07月26日に質問されました。  ·  閲覧回数 61.6k回  ·  ソース

James Skidmore picture
2009年07月26日

PHP コードのインライン ドキュメントにはさまざまな標準があることを知っています。 インライン ドキュメントの意味は次のとおりです。より適切な用語があれば修正してください。

/**
* This is the description for the class below.
*
* @package    my-package
* @subpackage my-subpackage
* @author     my-name
* @version    my-version
* ...
*/
class orderActions {
...

インライン ドキュメントの最良かつ最も広く受け入れられている形式は何ですか? 言い換えれば、誰もが同意し、意見に大きく基づいていないインライン ドキュメントの形式は何ですか。 誰もが知っておくべき PHP インライン ドキュメントの普遍的に受け入れられている形式ですが、質問者としてはまだわかりませんが、この質問に回答した後は、特定の意見を含めることなく、概要を理解することができます。

そのようなドキュメントを自動生成するツールはありますか、それとも手動で行う必要がありますか?

マニュアルの生成には興味がありません -- 上記のタイプのコード コメント、つまり「インライン ドキュメント」を生成する方法を知りたいです。

回答

zombat picture
2009年07月26日
45

PHPDoc は、あなたが投稿したものと同様、広く受け入れられている形式の PHP ドキュメントです。

Doxygenを使用してドキュメントを自動生成できます。

編集:コードでインライン ドキュメントを生成するという点で、プロジェクトのために戻って外部でこれを行うツールに出会ったことはありません。 通常、コーディング中にテンプレートを生成することは、IDE の領域に残されます。

Eclipse は実際にこれをうまくやっています (私が Eclipse で気に入っている数少ない点の 1 つです)。 主要な IDE には、このタイプのテンプレート生成を支援する機能が備わっている可能性があります。

troelskn picture
2009年07月26日
1

通常、docblock コメントは自分自身で作成しますが、一部の IDE はテンプレートを作成できると思います。

実際に、実行中のプログラムを追跡し、パラメーターの種類を検出して docblock コメントとして書き戻すプログラムを作成しました。 少しバグがありますが、ある程度機能します。

Jorge Olaf picture
2014年02月17日
1

非常に使いやすく、phpdoc と互換性のあるドキュメンテーターを作成しました。

例:

<?php
    $docs = new QuickDocumenter();
    $docs->parseString("
    /**
    *   Sanitize string
    *
    *   @since      1.0
    *   @version    1.0
    */
    ");
    foreach( $docs->result() as $doc)
    {
        highlight_string( print_r( $doc , true ) );
        echo "<hr/>";
    }
?>

Githubで見る:

https://github.com/olaferlandsen/QuickDocumenter

Thomas Owens picture
2009年07月26日
0

私はそれを完全には利用していませんが、 Doxygenはこのタスクに有望に見えます。

Java 用の JavaDoc ツールに精通している場合は、それに非常によく似ています。 Doxygen スタイルを使用し、ソース ファイルに対してツールを実行してドキュメントを作成します。

Jason picture
2009年07月26日
0

何をコーディングするかはわかりませんが、作業中に追加するスニペットがいくつかあります (Textmate を使用しています)。私のためにそれを行うシステム。

最初はより多くの作業ですが、長期的には価値があるようです