ドキュメントジェネレータ 詳細仕様 長谷川啓 2019.01.25

生成方法例 プログラム hcpp.exe -o a.i a.c -L a.j ... ソースファイル a.c b.c c.c ヘッダーファイル d.h hcpp.exe -o a.i a.c -L a.j hcc1.exe -o a.x a.i --generator /home/hase/docgen.dll ... doclink.exe -o mydoc.tex a.j a.x b.j b.x c.j c.x --exclude-dir /usr/include

ドキュメントの順序 入力ファイルの順 同じファイル内なら定義 or 宣言順 マクロ < 構造体等 < Typedef 名 < 変数 < 函数 前ページの生成方法例なら以下の順 a.j のマクロ b.j のマクロ c.j のマクロ a.x の構造体等 b.x の構造体等 c.x の構造体等 a.x の Typedef 名 b.x の Typedef 名 c.x の Typedef 名 a.x の変数 b.x の変数 c.x の変数 a.x の函数 b.x の函数 c.x の函数 呼び出し相関図

変数の例 FUNC_PTR func_tbl[] = { &add, &sub, &function_with_very_...long_name ... 変数の定義位置のプログラムテキストをそのまま参照 定義位置が複数行にまたがる場合は最大 L-1 行までにして、L 行目は ... にする ドキュメントの固定の幅を超える場合は途中を ... にする 定義 a.c:30 宣言 d.h:100 参照箇所 enter_func leave_func b.c:50 register_callback_function_with_very_...very_long ... /******************************* * 函数テーブル * この配列は register_callback_function_with... * でコールバック函数の登録に使用されるが、... ... 函数で参照される場合は函数名 変数の初期値でアドレスが参照さ れる場合は変数名 それ以外はファイル位置 最大 M 行まで 複数ある場合は最初の 1 つのみ 定義位置のコメント部分のプログラムテキストをそのまま参照 コメントがない場合は空行 最大 N 行まで L+M+N+2 が 1 ページに収まるようにする

typedef 名の例 変数と違うのは宣言がないこと typedef int FUNC(int); // このコメントはそのまま 定義 a.h:15 参照 a.c:20 b.c:30 c.c:40 /******************************* * コールバック函数の配列の要素 *******************************/ 変数と違うのは宣言がないこと

構造体の例 不完全型構造体 は除く タグ名のない構造体 は除く struct address { enum kind m_kind; /* 種別 */ int m_member_with_very_very_long_l..._name; uint8_t bytes[NBYTE]; // バイトデータ ... 構造体の例 宣言 d.h:500 不完全型構造体 は除く 参照箇所 getaddr add mul call div mod rsh lsh sub _goto a.c:70 _alloca // 3 番地コードのオペランド // を表現する構造体。 // スタック、静的変数、定数などを // 表す。 タグ名のない構造体 は除く typedef struct hoge_t { int a; char b[10]; } hoge; のような宣言に対しては構造体 hoge_t と typedef 名 hoge のドキュメントを出すようにする

マクロの例 #define my_va_arg(ap, T) \ (char*)ap += sizeof(T), \ /* compound_statement expression...使えば */ \ ... マクロの例 定義 d.h:789 参照箇所 a.c:5 a.c:7 a.c:12 b.c:34 d.h:1234 d.h:5678 // ap ポインタの指すアドレスから // 型 T の変数を読みだした値を返す // マクロ。読みだした後に ap を sizeof(T) 進める。 // これだとアラインメントがマズい

函数の例 uint32_t register_callbak_function_with_very_long_name(... FUNC_PTR* a, // ここのコメントはそのまま表示 ... 函数の例 函数の定義位置のプログラムテキストをそのまま参照 ボディの始まりの { の前まで 最大 X 行 定義 very_very_long_long_file_....name.c:1234567 宣言 directory1/directory2/direc.../lon...name.h:100 参照箇所 func1 func2 hoge.c:70 function_with_very_very_long_long_long_..._name ... 最大 Y 行まで /******************************* * コールバック函数を登録する * この函数は第 1 引数で指定された配列のアド... ... 定義位置のコメントのプログラムテキストをそのまま参照 コメントがない場合は空行 最大 Z 行まで 函数の流れグラフを配置する領域 X+Y+Z+2 が 1 ページに収まるようにする

隣以外で同じページのブロックの辺はこの位置に描く 函数流れグラフの例 e52 と e42 が重なってよいのはここだけ B1 ループの辺はこの位置に辺を描く B2 d d d 流れグラフ (コンパイラII pp646) 他のペ ージから複数の辺がある場合は1本にする B3 1 ページに定数個 の基本ブロックを 縦に等間隔で配置 する d d B4 B5, B9 B6

前のページのブロックからの辺はこの位置に描く B2 B3 B5 前のページのブロックからの辺はこの位置に描く d d B6 d 隣合うブロックの辺この位置に辺を描く B7 d d B8 B10

B2 B7 B9 d B10 d

遷移元の基本ブロックをテキストで書くが、入らなければ途中でちぎる e121,123 と e121,124 が重なってよいのはここだけ 他のページからの辺は1つにまとめる 遷移元の基本ブロックをテキストで書くが、入らなければ途中でちぎる e121,123 と e121,124 が重なってよいのはここだけ B60 B61 ... d B70 B... B121 B80 ... d d B90 . B122 d d d e121,123 と e80,123 が重なってよいのはここだけ B123 B124 e121,124 と e90,124 が重なってよいのはここだけ

呼び出し相関図の例 func00 葉に向かう辺をもつ 木構造にする func10 深さ優先でグラフを 描く func20 定義がない函数の呼び出しはこのようにする lib_func func32 func31 すでに func31 はグラフに現れているのでこうする func31 func00 再帰はこうなる

函数名が一定の幅に収まるように途中を...にする 呼び出し相関図の例 func00 func10 func_with_...20 func30 函数名がページにおさまらない場合は改ページする func31_wi... func21, func22 func11, func12, func13

呼び出し相関図の例 subr00 subr10 subr20 subr21 subr22 subr23 縦に収まらない場合は改ページする subr11 subr12 subr13 ...