web-dev-qa-db-ja.com

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

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

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

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

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

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

phpdocumentationcomments
34
James Skidmore

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

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

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

実際、Eclipseはこれについてまともな仕事をします（Eclipseが好きな数少ないことの1つです）。Netbeansも同様です。メジャーIDEは、このタイプのテンプレート生成を支援する機能を備えている可能性があります。

43
zombat

から選ぶ：

ウィキペディアの記事、「ドキュメントジェネレーターの比較」、「言語別」セクション も参照してください。

8
Benoit Blanchon

私は非常に使いやすく、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

1
Jorge Olaf Erlandsen

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

実際に 実行中のプログラムをトレースし、パラメータタイプを検出し、それらをdocblockコメントとして書き戻すことができるプログラムを作成します 。少しバグがありますが、機能します。

1
troelskn

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

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

0
Thomas Owens

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

最初はもっと手間がかかりますが、長期的には価値があるようです

0
Jason