私は最終的に、Microsoft の XML ドキュメント形式によって課せられた山かっこ税を放棄し (そして、MSVC 環境はまだC++ プロジェクトに対してそれをうまく処理していないため、ポイントは何ですか)、現在のプロジェクトを Doxygen を使用するように切り替えています。 Javadoc スタイルの構文。
素晴らしいです。インライン ドキュメントは読みやすく入力しやすく、生成された出力は非常に便利で多用途です。特に、このMULTILINE_CPP_IS_BRIEFオプションをオンにすると、必要なだけ「簡単な」説明を書き、「詳細」ドキュメントを空白行を使用して段落に分割できます。言い換えると：
/// Changes the active viewing area of the currently selected region.
///
/// The modification is merely enqueued. This function has no effect until the
/// FlushRegion() function is called.
///
/// Newly-exposed regions will not be repainted automatically. The user must also
/// call the UpdateRegion() function on these regions to cause their contents to
/// be redrawn.
///
/// @param dx The amount, in pixels, to shift the visible region horizontally.
/// @param dy The amount, in pixels, to shift the visible region vertically.
///
/// @remarks
/// Note that this function is reentrant, but not thread-safe!
void ScrollRegion(int dx, int dy);
@briefこれにより、使用しなければならないや などのノイズの多いメタコマンドの数を抑えながら、まさに私が望む出力\detailsが得られます。
問題は、「詳細」セクションで (暗黙のうちに) 行ったように、「備考」セクションに 2 番目の段落を含めようとしたときに発生します。例えば：
/// Changes the active viewing area of the currently selected region.
///
/// The modification is merely enqueued. This function has no effect until the
/// FlushRegion() function is called.
///
/// Newly-exposed regions will not be repainted automatically. The user must also
/// call the UpdateRegion() function on these regions to cause their contents to
/// be redrawn.
///
/// @param dx The amount, in pixels, to shift the visible region horizontally.
/// @param dy The amount, in pixels, to shift the visible region vertically.
///
/// @remarks
/// Note that this function is reentrant, but not thread-safe!
///
/// If thread safety is required, the user must handle locking and unlocking
/// the region manually.
void ScrollRegion(int dx, int dy);
@remarks生成された出力では、セクションの 2 番目の段落が注釈の一部として解釈されません。<simplesect kind="remark">HTML 出力では同じレベルにインデントされておらず、XML 出力ではタグの下に配置されていないため、わかります。
2 番目のパラグラフの先頭に@parコマンドを追加しようとしましたが、それも思い通りにはなりませんでした。新しい段落は、まだ「備考」セクションの子ではありません。XML 出力では<simplesect kind="para">、元のタグの兄弟である新しいタグ内に配置されてい<simplesect kind="remark">ます。
これを調査しているときに、他の誰かが@remarksコマンドを複製したことがわかりました。
/// Changes the active viewing area of the currently selected region.
///
/// The modification is merely enqueued. This function has no effect until the
/// FlushRegion() function is called.
///
/// Newly-exposed regions will not be repainted automatically. The user must also
/// call the UpdateRegion() function on these regions to cause their contents to
/// be redrawn.
///
/// @param dx The amount, in pixels, to shift the visible region horizontally.
/// @param dy The amount, in pixels, to shift the visible region vertically.
///
/// @remarks
/// Note that this function is reentrant, but not thread-safe!
/// @remarks
/// If thread safety is required, the user must handle locking and unlocking
/// the region manually.
void ScrollRegion(int dx, int dy);
それは私が望む出力を生成します。両方の段落はXML 出力<para>の タグの下の<simplesect kind="remark">タグにネストされており、視覚的な関係は HTML 出力で正しいです。しかし、それは醜く、私には間違いのように見えます。
私が見逃しているこれを行う標準的な方法はありますか？確かに、ドキュメントの「コメント」セクションに複数の段落が必要な人は私が初めてではありません...そして、これはに限定されません@remarks。@internalたとえば、同じことが起こります。
Doxygen の最新バージョン (1.8.2) がインストールされていますが、これがバージョン固有のものであるとはとても思えません。