差分

このページの2つのバージョン間の差分を表示します。

--- programing:doxygen:doxygen-coding-rules-c [2020/02/25 02:00] – [コメント規約ルール例] yoko
+++ programing:doxygen:doxygen-coding-rules-c [2020/12/03 23:11] (現在) – [テーブル] yoko
@@ 行 15: / 行 15: @@
 設定ファイル「`Doxyfile`」は、`doxygen -g` コマンド実行でデフォルト値ファイルが生成できる。特に下記項目について留意して設定する。
-^ 必須  ^ 設定項目                     ^ 設定値                     ^ 備考                                             ^
+^ 必須  ^ 設定項目                 ^ 設定値                ^ 備考                                                                            ^
-| ◎   | `PROJECT_NAME`           | `"μNETマスター通信 Project"`  | プロジェクト名またはプログラム名を記述する                          |
+| ◎     | `PROJECT_NAME`           | `"サンプル Project"`  | プロジェクト名またはプログラム名を記述する                                      |
-| ◎   | `OUTPUT_LANGUAGE`        | `Japanese`              | 日本語出力する                                        |
+| ◎     | `OUTPUT_LANGUAGE`        | `Japanese`            | 日本語出力する                                                                  |
-| ◎   | `OPTIMIZE_OUTPUT_FOR_C`  | `YES`                   | C/C++言語ではYESに設定                                |
+| ◎     | `OPTIMIZE_OUTPUT_FOR_C`  | `YES`                 | C/C++言語ではYESに設定                                                          |
-|     | `PROJECT_NUMBER`         | `1.1`                   | バージョン情報が必要であれば記述する                             |
+|       | `PROJECT_NUMBER`         | `1.1`                 | バージョン情報が必要であれば記述する                                            |
-|     | `RECURSIVE`              | `NO` or `YES`           | `YES`にするとDoxygen実行ディレクトリ以下を再帰的に探してドキュメントを生成する  |
+| △     | `RECURSIVE`              | `NO` or `YES`         | `YES`にするとDoxygen実行ディレクトリ以下を再帰的に探してドキュメントを生成する  |
-|     | `GENERATE_LATEX`         | `NO`                    | LaTeX出力をしない（時間がかかるので、通常は抑制し、必要時にYESにする）        |
+|       | `GENERATE_LATEX`         | `NO`                  | LaTeX出力をしない（時間がかかるので、通常は抑制し、必要時にYESにする）          |
-|     | `HAVE_DOT`               | `NO`                    | graphvizを使用しない（時間がかかるので、通常は抑制し、必要時にYESにする）     |
+|       | `HAVE_DOT`               | `NO`                  | graphvizを使用しない（時間がかかるので、通常は抑制し、必要時にYESにする）       |
 コメント規約ルール例
 -------------------
-以下の **ファイル**，**グローバル関数**，**グローバル変数**，**来歴** のコメントについては最低限記述。
+以下の **ファイル**，**グローバル関数**，**グローバル変数**，**来歴** のコメントについては最低限記述する。`doxygen` コマンド実行でドキュメントを生成する。
+### ファイル・コメント
+ファイルの先頭に、そのファイルの概要説明を記述。
-FIXME 工事中
+<code c>
+/**
+ * @file   sample.c
+ * @brief  GCC Test sample program
+ * @author T.Yokobayashi de JR4QPV
+ * @date   2020/04/16
+ */
+</code>
+  * 必要があれば、`@details` に詳細説明を記載。
+### グローバル関数・コメント
+関数の直前に記述。グローバル関数は `************` 行を上下に付加して強調する。
+<code c>
+/**
+ *****************************************************************************
+ * @brief  Sample main program
+ * @param  argc 引数の個数
+ * @param  argv 引数文字列
+ * @retval 0 正常
+ * @retval 1 引数エラー
+ * @details
+ *****************************************************************************
+ */
+int main(int argc, char *argv[])
+{
+    int i;
+</code>
+  * 戻り値は`retval`で数値を指定せず「`@return =0:正常, =-1:異常`」などのように簡単に記述してもよい。
+  * `@attention`の注意事項は無ければ省略する。
+  * 引数と戻り値がない時は「`none`」と記述する。
+`@param none`
+`@return none`
+### ファイル内関数・コメント
+関数の直前に記述。ファイル内スコープの static関数 は、Doxygenではドキュメント出力されないようだが、ソースをみれば関数の使い方が判るように以下のように記載しておく。
+<code c>
+/**
+ * @brief  サブルーチン関数
+ * @param  mode モード指定(0 or 1)
+ * @return 終了コード（=0:正常, ≠0:エラー）
+ * @details
+ *  - modeが不正な時は「-1」が戻る
+ */
+static int sub_function(int mode)
+{
+    int rc;
+</code>
+### グローバル変数・コメント
+グローバル変数の簡易説明を下記のように記述。
+<code c>
+T_MYTBL _mytbl[16];	//!< 管理テーブル
+</code>
+  * `//!<` は `///<` と書いてもよい。
+  * `/*!< Node管理テーブルの実態 */`のよう記述すると、別セクションに独立に説明が出力される。
+### 来歴・コメント
+ファイルの末尾に、そのファイルの来歴説明を記述。
+<code c>
+/**
+ *----------------------------------------------------------------------------
+ * @file   main.c
+ * History
+ * -------
+ * - 2018/11/04 New created.(By T.Yokobayashi)
+ * - 2020/04/16 Write a Doxygen comment.
+ */
+</code>
+  * `@file`の記述がキーとなるので、先頭に記述したファイル名と必ず一致するようにする。
+  * 最低限以下の情報は記載する。細かい変更はGitで管理できる。
+「新規作成日・作成者」，「大きな機能変更」，「大きなバグ修正」
+その他のコメント
+---------------
+### 覚え書き
+下記記述で、関数の使用法などの留意点などを残す。
+<code>
+  @note メモメモ
+</code>
+### 残作業
+下記記述で、残作業をドキュメントに残す。
+<code>
+///@todo 残作業メモ
+</code>
+### バグ
+下記記述で、バグ情報をドキュメントに残す。
+<code>
+///@bug バグ情報メモ
+</code>
+補足
+----
+  * 説明文の記述には[[http://kasamotokun.endless-world.net/doxygen-manual/markdown.html|Markdown]]記法が使える。なので、「`## `」で見出し，「`- `」文字で箇条書き になる。
+  * その他にも色々なコマンドがある。
+参考
+----
+. [[http://www.02.246.ne.jp/~torutk/cxx/doxygen/doxygenstyles.html|Doxygenコメント規約例]]
+{{tag>Rules}}