Doxygenで@parとリストを混ぜてみた: だらろぐ

2009/05/28

Doxygenで@parとリストを混ぜてみた

Doxygenの日本語訳マニュアルを見ていると、@parコマンドの説明に気になる記述がありました。

パラグラフタイトルがない場合、新しいパラグラフを開始します。これは、他のパラグラフコマンド (\param や \warningなど) の内部でも機能します。その際、そのコマンドを終了させることはありません。

つまり、パラグラフコマンドに2つめ以降のパラグラフを追加できるの？単に同じようにインデントされるから、続いてるように見えるだけでなく？

というわけで、試してみることにしました。普通にパラグラフコマンドに続けただけだと、上に書いた疑問が拭い去れないので、じゃあ、リストに入れてみたらどうなんだ、ということで表題のようなことになったわけです。

リスト内@par

まずは実物をご覧下さい。

項目 1

項目 1.1

項目 1.2
リスト内で改段
@par で段落を作ってみる。ここは項目 1.2の続き。

タイトル無しの新たな @par コマンドで更に続きの段落。

@par の前で行を空けても続きの段落。(ソース上はこの段落の前に空行が入っている。)

項目 1.3

項目 2

ソースのこの部分は以下のようになってます。

/// - 項目 1
///     - 項目 1.1
///     - 項目 1.2
///     @par リスト内で改段
///     @@par で段落を作ってみる。
///     ここは項目 1.2の続き。
///     @par
///     タイトル無しの新たな @@par コマンドで更に続きの段落。
///     
///     @par
///     @@par の前で行を空けても続きの段落。(ソース上はこの段落の前に空行が入っている。)
///     - 項目 1.3
///     - 項目 2

@parコマンドの部分は、通常ならここまでは字下げされません。確かにリストの項目の中身になっているようです。それどころか、後続の@parの前に空行が入っても続きのパラグラフだと認識されるようです。

@par内リスト

次に、1つめの@parの前に空行を入れてみました。ソースはこうなってます。

/// - 項目 1
///     - 項目 1.1
///     - 項目 1.2
///
///     @par 1行空けてから段落を作ってみる
///     行が空いたのでここはリストの続きじゃない。
///     - 段落内リストになった。(インデントされているが、行頭の記号が1階層目のになってる。)
///         - 下の階層
///         @par @@par はネストしない
///         リストの項目と行を空けずに @@par コマンドを書いてみた。
///         @@par コマンド内のリストの内部にはならず、リストが終了して新たな段落になった。
///         - 次の項目は新たなリストになる。

項目1.2の後に空行が入っているので、そこでリストの終わりとなります。前のパラグラフと繋げたいなら、1つめの@parの前には空行は入れられません。

生成されたドキュメントはこの様になります。

項目 1

項目 1.1

項目 1.2

1行空けてから段落を作ってみる
行が空いたのでここはリストの続きじゃない。

段落内リストになった。(インデントされているが、行頭の記号が1階層目のになってる。)

下の階層

@par はネストしない
リストの項目と行を空けずに @par コマンドを書いてみた。 @par コマンド内のリストの内部にはならず、リストが終了して新たな段落になった。

次の項目は新たなリストになる。

@parの内容の直後に空行を置かずに記述したリストは、インデントされてパラグラフに含まれています。いきなりリストの2階層目から始まった訳ではありません。行頭記号は1階層目に使われるものになっています。

更に、@par内リストの項目に続けて@parを書いてみました。その場合は、更に内側の階層になることはなく、そこまでのリストおよびパラグラフが終了して、新たなパラグラフとなりました。

リスト内@par内リスト

@par内リスト内@parは出来ないことは分かりました。では、もともと階層構造を持つリストについて、リスト内@par内リストはどうでしょうか。以下のソースで試してみました。

/// - 項目 1
///     - 項目 1.1
///     - 項目 1.2
///     @par リスト内で改段
///     @@par で段落を作ってみる。
///     ここは項目 1.2の続き。
///     @par
///     新たな @@par コマンドで更に続きの段落。
///         - ここに下位の項目を作ってみる。
///         - もういっちょ。
///             - 更に下げてみたり。
///     @par
///     新たな @@par は前の @@par と同じレベルに戻るらしい。
///             - @@par 直下のレベルに戻された。
///             (ソース上は「更に下げてみたり。」の行と同じインデント。)
///     - 項目 1.3
/// - 項目 2

結果は以下の通りです。リスト内@par内リストは出来ました。

項目 1

項目 1.1

項目 1.2
リスト内で改段
@par で段落を作ってみる。ここは項目 1.2の続き。

新たな @par コマンドで更に続きの段落。

ここに下位の項目を作ってみる。

もういっちょ。

更に下げてみたり。

新たな @par は前の @par と同じレベルに戻るらしい。

@par 直下のレベルに戻された。 (ソース上は「更に下げてみたり。」の行と同じインデント。)

項目 1.3

項目 2