22

javadoc / phpDocumentorスタイルで文書化したいインクルードがたくさんある、いくつかの完成した古いPHPプロジェクトがあります。

各ファイルを手動で処理し、ドキュメントと一緒にコードレビューを強制するのが最善ですが、時間の制約から、タスクを可能な限り自動化するのに役立つツールに興味があります。

私が考えているツールは、理想的には次の機能を備えています。

  • PHPプロジェクトツリーを解析し、文書化されていないファイル、クラス、および関数/メソッド（つまり、適切なdocblockコメントが欠落している要素）がある場所を教えてください

  • 空の構造を作成し、理想的にはファイルをエディター（内部または外部は関係ありません）で開いて説明を入力できるようにすることで、不足しているdocblockを途中で簡単に追加する方法を提供します。

オプション：

  • パラメータタイプ、戻り値などの自動認識。しかし、それは実際には必要ありません。

問題の言語はPHPですが、C/Javaツールで微調整を行うとPHPファイルを処理できる可能性があると想像できます。

素晴らしいご意見ありがとうございます！

4

9 に答える 9

3

PHPCS については既に説明したので、Reflection API を投入して、欠落している DocBlocks をチェックします。以下にリンクされている記事は、問題へのアプローチ方法に関する短いチュートリアルです。

また、インクルード、グローバル変数、関数、パラメーター、クラス、定数、プロパティ、メソッド (およびその他のもの) のファイル ページ ブロックと DocBlocks を作成できるPEAR パッケージもあります。PHP_DocBlockGenerator

于 2010-03-05T15:25:51.870 に答える
2

php-tracer-weaverは、コードを計測し、ランタイム分析によって推定されたパラメーターの型で docblock を生成できます。

于 2009-12-20T19:20:22.387 に答える
1

phpDocumentor の 1.4.x バージョンには -ue オプション (--undocumentedelements) [1] があり、ドキュメントの実行中に生成される errors.html ページに、ドキュメント化されていない要素が警告としてリストされます。

さらに、PEAR の PHP_DocBlockGenerator [2] は、不足している docblock を生成できるようです。

[1] -- http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#using.command-line.undocumentedelements

[2] -- http://pear.php.net/package/PHP_DocBlockGenerator

于 2009-12-20T20:23:39.063 に答える
0

「javadoc」タイプのデータを入力する問題を実際に自動化したいですか?

DMS Software Reengineering Toolkitは、これを行うように構成できます。

コンパイラと同じようにソーステキストを解析し、内部コンパイラ構造を構築し、任意の分析を実装し、それらの構造に変更を加え、構造の変更に従って変更されたソーステキストを再生成 (「prettyprint」) します。元のテキストのコメントや書式も保持されます。もちろん、追加のコメントを挿入すると表示されます。これが主な目標のようです。DMS は、 PHPを含む多くの言語でこれを行います。

あなたがしたいことは、各PHPファイルを解析し、すべてのクラス/メソッドを見つけ、そのエンティティであるべき「javadoc」コメントを生成し（クラスとメソッドの違いですよね？）、対応するコメントが実際にコンパイラ構造。そうでない場合は、単に挿入します。最終結果を PrettyPrint します。コードを表すコンパイラ構造にアクセスできるため、提案したように、パラメーターを生成して情報を返すことは難しくありません。もちろん、意図した目的に関するコメントを生成することはできません。ただし、後で入力するためのプレースホルダーが生成される可能性があります。

于 2010-03-06T16:53:31.430 に答える
0

それが助けになるかどうかはわかりませんが、Codesniffer が関数/メソッドを指摘できれば、まともな PHP IDE (私は PHPEd を提供しています) を使用して、各関数の PHPDoc コメントを簡単に検査およびスキャフォールディングできます。

/**各関数の上に入力して ENTER を押すだけで、PHPEd は@param1、@param1、@returnなどを正しく入力してコードを自動補完し、追加の説明の準備が整います。例を提供するために最初に試したのは次のとおりです。

  /**
  * put your comment here...
  * 
  * @param mixed $url
  * @param mixed $method
  * @param mixed $timeout
  * @param mixed $vars
  * @param mixed $allow_redirects
  * @return mixed
  */
  public static function curl_get_file_contents($url, $method = 'get', $timeout = 30, $vars = array(), $allow_redirects = true)

これは次のように簡単に調整できます。

  /**
  * Retrieves a file using the cURL extension
  * 
  * @param string $url
  * @param string $method
  * @param int $timeout
  * @param array $vars parameters to pass to cURL
  * @param int $allow_redirects boolean choice to follow any redirects $url serves up
  * @return mixed
  */
  public static function curl_get_file_contents($url, $method = 'get', $timeout = 30, $vars = array(), $allow_redirects = true)

正確には自動化されたソリューションではありませんが、怠惰な開発者としての私にとっては十分に迅速です:)

于 2010-03-07T01:17:35.813 に答える
0

この機能には、標準の PEAR または Zend 標準を使用して、codesniffer を使用しています。その場でファイルを編集することはできませんが、欠落している docblock の行と説明を含むリストが確実に表示されます。

HTH、Jc

于 2009-12-20T20:31:36.127 に答える