web-dev-qa-db-ja.com

@fileoverviewでのJSプログラムフローの説明

他の人のJavaScriptコードを編集する必要があります。このコードは通常、Web APIからいくつかのデータをロードし、テーブルを生成してHTMLページに配置し、いくつかのイベントハンドラーをアタッチします。

非同期の性質のため、プログラムフローはかなり混乱しているので、簡単に文書化しようとしています。そうしないと、コードのどの部分を変更する必要があるかを理解しようとして迷子になります。たとえば、Web APIからデータをロードした後、テーブルに配置する前にいくつかの値を変更する必要がある場合、データのロードが発生する場所とHTMLレンダリングが発生する場所を把握する必要があります。

ここに私がそれをしている方法があります：

/**
 * @fileOverview Custom code for the Candidates List page.
 * Program flow on page load:
 * - customSearchInit()
 *   - initSearchPage()
 *     - populateDropdownFields()
 *     - LoadAdditionalListDataAndContinue()
 *       - loadListData()
 *         - generateHtmlTable()
 *         - finishAsync()
 *           - completePageLoad()
 */

プログラムフローを文書化するための推奨/一般的な構文はありますか？これは一般的な方法ですか？

javascriptdocumentationcomments
2
user238671

人間が消費できる方法で動作を説明する一般的な方法は、 シーケンス図 を使用することです。システムコンポーネント間のコラボレーションを示し、同時実行や非同期メッセージなどの複雑さを処理できます。

あなたのコード内構文は理解するのが難しいと思いますが、代わりにプロジェクトのドキュメントにあるシーケンス図を作成します JSDoc （シーケンス図を参照するには、JSDocを使用している@fileOverviewタグから）リンクを参照してください。

/**
 * @fileOverview Custom code for the Candidates List page.
 * See [this diagram](../docs/candidates-sequence.png) to understand the behavior of the page load
 */

テキストベースのシーケンス図記述ツール PlantUML を使用してシーケンス図を作成することを好みます。オープンソースであり、テキストベースであるため、バージョン管理が容易です。本当に必要な場合は、<pre><code>タグでラップすることにより、PlantUML コードをファイルドキュメントに直接挿入 にすることもできます。

このようなドキュメントは、実装が変更されると、実際の実装から逸脱することが多いことに注意してください。

1
Samuel