0

私は、Yet Another PHP Framework を面白おかしくやっており、ドキュメントの最初のラウンドを行っています。少しコーディングし、コーディングした内容を文書化し、さらにコーディングし、コードの新しい機能を反映するように文書を調整することを計画しています。これを繰り返します。たとえば、現時点では構成はかなり手動で面倒ですが、今日のように構成する必要があるため、文書化しています。セットアップの自動化まで進んだら、現在のステータスを反映するために、それらの部分を書き直す予定です。

私が疑問に思っているのは、参照ドキュメントを最新の状態に保つためのヒューリスティックはありますか? API の文書化 (PHPDoc などで無料で提供されているもの) について話しているだけでなく、より大きなスキームについても話しているのです。チュートリアル、概要記事、すべて。何か特別なものを更新するのを忘れる可能性を最小限に抑える良い方法はありますか?

4

2 に答える 2

2

私たちは最初の仕事で似たようなことをしました。 

/*
<document>
    <version>x.y.z.g</version>
    <date>10.4.2009</version>
    <key>fff#ggg</key>
    <more...................../more>
</socument>
*/
int ggg(char x){
...
...
}

ドキュメンター アプリは日付の違いをテストし (それ以降のバージョンではソース管理に対して)、不一致が疑われる場合は警告フラグを立てます。

PHP では、既知の便利な形式で保持されている場合、コードの注釈をスキャンするために何かを作成することはそれほど難しくありません。

于 2009-04-11T00:07:46.033 に答える
1

非ローカリゼーションのため、これは非常に難しい問題です。1 つのドキュメント要素の情報が、複数のコードの場所に依存したり、影響を与えたりする可能性があり、コードの場所を表示しているときに、通常、ドキュメントを認識していません。したがって、コードの変更によってドキュメントの更新がトリガーされない場合があります。

変更がドキュメントの変更をトリガーする各コード セクションに、なんらかの形式の明示的なリンクを含めることが重要だと思います。人々にテキストを更新してもらうのは大変なので、影響を受ける可能性のある領域を人々に見つけてもらうのは困難です。特に、より一般的な資料 (API など) の場合はそうです。

複数の場所で言及されている機能を更新する場合、更新の潜在的な必要性をどこで探すべきかについて、少なくともそのリストが必要です。

于 2009-04-10T23:13:25.680 に答える