2.2.3. コメントおよびドキュメント

すべてのプローブおよび関数には、目的、提供するデータ、および実行するコンテキストを記述するコメントブロック (割り込み、プロセスなど) が含まれている必要があります。コードの読み取りでは、不明瞭なエリアでコメントを使用します。

特殊形式のコメントは、多くの tapset から自動的に抽出され、本ガイドに含まれています。これにより、tapset の貢献者が tapset を作成し、同じ場所で文書化するのに役立ちます。tapset の文書化に指定される書式は、以下のとおりです。

/**
 * probe tapset.name - Short summary of what the tapset does.
 * @argument: Explanation of argument.
 * @argument2: Explanation of argument2. Probes can have multiple arguments.
 *
 * Context:
 * A brief explanation of the tapset context. 
 * Note that the context should only be 1 paragraph short.
 *
 * Text that will appear under "Description."
 *
 * A new paragraph that will also appear under the heading "Description".
 *
 * Header:
 * A paragraph that will appear under the heading "Header".
 **/

以下に例を示します。

/**
 * probe vm.write_shared_copy- Page copy for shared page write.
 * @address: The address of the shared write.
 * @zero: Boolean indicating whether it is a zero page
 *         (can do a clear instead of a copy).
 *
 * Context:
 *  The process attempting the write.
 *
 *  Fires when a write to a shared page requires a page copy.  This is
 *  always preceded by a vm.shared_write.
 **/

自動生成される Synopsis コンテンツをオーバーライドするには、以下を使用します。

 * Synopsis:
 * New Synopsis string
 *

以下に例を示します。

/**
 * probe signal.handle - Fires when the signal handler is invoked
 * @sig: The signal number that invoked the signal handler
 *
 * Synopsis:
 * <programlisting>static int handle_signal(unsigned long sig, siginfo_t *info, struct k_sigaction *ka,
 * sigset_t *oldset, struct pt_regs * regs)</programlisting>
 */

エントリーの Synopsis の内容を上書きしても必要なタグが自動的に作成されないため、この例では <programlisting> タグの使用を推奨しています。

コメントの DocBook XML 出力を改善するため、コメントに以下の XML タグを使用することもできます。