Markdown のサポートは Doxygen バージョン 1.8.0 で導入されました。これは John Gruber によって書かれたプレーンテキストの書式設定構文であり、以下の設計目標を持っています
Markdown の書式設定構文の設計目標は、可能な限り読みやすくすることです。アイデアは、Markdown で書式設定されたドキュメントが、タグや書式設定の指示でマークアップされているように見えないように、プレーンテキストとしてそのまま公開できることです。Markdown の構文は既存のいくつかのテキストから HTML へのフィルターに影響を受けていますが、Markdown の構文の最大のインスピレーション源はプレーンテキストメールの形式です。
次のセクションでは、標準の Markdown 機能について簡単に説明します。詳細については、Markdown サイトを参照してください。
例えば、PHP Markdown Extra や GitHub Flavored Markdown など、いくつかの機能強化がなされました。Markdown 拡張のセクションでは、Doxygen がサポートする拡張機能について説明します。
最後に、Doxygen の詳細セクションでは、Markdown 標準の Doxygen の実装に関するいくつかの詳細について説明します。
Doxygen が Markdown をサポートする前から、Markdown と同じ段落処理方法をサポートしていました。段落を作成するには、連続するテキスト行を1つ以上の空白行で区切るだけです。
例
Here is text for one paragraph. We continue with more text in another paragraph.
Markdown と同様に、Doxygen は2種類のヘッダーをサポートしています
レベル1または2のヘッダーは次のように作成できます
This is a level 1 header ======================== This is a level 2 header ------------------------
ヘッダーの後には、= または - のみが含まれる行が続きます。= または - の正確な量は、少なくとも2つあれば重要ではありません。
または、行の先頭に # を使用してヘッダーを作成できます。行の先頭にある # の数によってレベルが決まります (最大6レベルがサポートされています)。ヘッダーは任意の数の # で終了できます。
例を次に示します
# This is a level 1 header ### This is level 3 header #######
ブロッククォートは、各行を1つ以上の > で始めることで作成できます。これは、テキストのみのメールで使用されるものと似ています。
> This is a block quote > spanning multiple lines
リストとコードブロック (下記参照) はクォートブロック内に表示できます。クォートブロックはネストすることもできます。
Doxygen は、誤検出を避けるために (最後の) > 文字の後にスペースを入れる必要があることに注意してください。つまり、次のように記述した場合
0 if OK\n >1 if NOK
2行目はブロッククォートとして認識されません。
簡単な箇条書きリストは、行を -, +, または * で始めることで作成できます。
- Item 1 More text for this item. - Item 2 + nested list item. + another nested item. - Item 3
リスト項目は複数の段落にまたがることができ (各段落が適切なインデントで始まる場合)、リストはネストできます。次のように番号付きリストを作成することもできます
1. First item. 2. Second item.
Doxygen の詳細については、リストの拡張も必ずお読みください。
事前フォーマットされた逐語的なブロックは、テキストブロックの各行を少なくとも4つの余分なスペースでインデントすることで作成できます
This a normal paragraph
This is a code block
We continue with a normal paragraph again.
Doxygen はコードブロックから必須のインデントを削除します。段落の途中でコードブロックを開始できないことに注意してください (つまり、コードブロックの前の行は空である必要があります)。
Doxygen がインデントをどのように処理するかについては、標準の Markdown とは少し異なるため、コードブロックのインデントのセクションを参照してください。
少なくとも3つ以上のハイフン、アスタリスク、またはアンダースコアを含む行に対して水平線が生成されます。行には任意の量の空白を含めることもできます。
例
- - - ______
コメントブロックでアスタリスクを使用すると機能しないことに注意してください。詳細については、アスタリスクの使用を参照してください。
ハイフンを使用し、前の行が空でない場合、ハイフンのシーケンスに少なくとも1つの空白を使用する必要があることに注意してください。そうしないと、レベル2のヘッダーとして認識される可能性があります (ヘッダーを参照)。
テキストフラグメントを強調するには、フラグメントをアンダースコアまたはアスタリスクで開始および終了します。2つのアスタリスクまたはアンダースコアを使用すると、強い強調が生成されます。3つのアスタリスクまたはアンダースコアは、前の2つのオプションの強調を結合します。
例
*single asterisks* _single underscores_ **double asterisks** __double underscores__ ***triple asterisks*** ___triple underscores___
Doxygen が強調/打ち消し線スパンを標準/Markdown GitHub Flavored Markdown とは少し異なる方法で処理する方法の詳細については、強調と打ち消し線の制限のセクションを参照してください。
テキストフラグメントを打ち消し線で表示するには、フラグメントを2つのチルダで開始および終了します。
例
~~double tilde~~
Doxygen が強調/打ち消し線スパンを標準 Markdown / GitHub Flavored Markdown とは少し異なる方法で処理する方法の詳細については、強調と打ち消し線の制限のセクションを参照してください。
コードスパンを示すには、それをバックティック ( ` ) で囲む必要があります。コードブロックとは異なり、コードスパンは段落内にインラインで表示されます。例
Use the `printf()` function.
コードスパン内にリテラルのバックティックまたは単一引用符を表示するには、二重バックティックを使用します。つまり
To assign the output of command `ls` to `var` use ``var=`ls```. To assign the text 'text' to `var` use ``var='text'``.
Doxygen がコードスパンを標準 Markdown とは少し異なる方法で処理する方法の詳細については、コードスパンの制限のセクションを参照してください。
Doxygen は、Markdown で定義された2つのリンク作成スタイル (インラインと参照) の両方をサポートしています。
どちらのスタイルでも、リンク定義は [角括弧] で区切られたリンクテキストで始まります。
インラインリンクの場合、リンクテキストの後に URL とオプションのリンクタイトルが続き、これらが一緒に一対の通常の括弧で囲まれます。リンクタイトル自体は引用符で囲まれます。
例
[The link text](http://example.net/) [The link text](http://example.net/ "Link title") [The link text](/relative/path/to/index.html "Link title") [The link text](somefile.html)
さらに、Doxygen は文書化されたエンティティをリンクする同様の方法を提供します
[The link text](@ref MyClass)
参照の最初の非空白文字が # である場合、これは Doxygen リンクとして解釈され、@ref コマンドとして置き換えられます
[The link text](#MyClass)
は次のように解釈されます
@ref MyClass "The link text"
URL をインラインで配置する代わりに、リンクを個別に定義し、テキスト内から参照することもできます。
リンク定義は次のようになります
[link name]: http://www.example.com "Optional title"
二重引用符の代わりに、単一引用符または括弧もタイトル部分に使用できます。
定義されると、リンクは次のようになります
[link text][link name]
リンクテキストと名前が同じ場合、次も
[link name][]
あるいは
[link name]
リンクを参照するために使用できます。リンク名の一致は大文字と小文字を区別しないことに注意してください。これは次の例に示されています
I get 10 times more traffic from [Google] than from [Yahoo] or [MSN]. [google]: http://google.com/ "Google" [yahoo]: http://search.yahoo.com/ "Yahoo Search" [msn]: http://search.msn.com/ "MSN Search"
リンク定義は出力に表示されません。
インラインリンクと同様に、Doxygen はリンク定義内で @ref もサポートします
[myclass]: @ref MyClass "My class"
画像の Markdown 構文はリンクの構文と似ています。唯一の違いは、リンクテキストの前の追加の ! です。
例
  ![Caption text][img def] ![img def] [img def]: /path/to/img.jpg "Optional Title"
ここでも、@ref を使用して画像をリンクできます
 ![img def] [img def]: @ref image.png "Caption text"
キャプションテキストはオプションです。
URL または電子メールアドレスへのリンクを作成するには、Markdown は次の構文をサポートしています
<http://www.example.com> <https://www.example.com> <ftp://www.example.com> <mailto:[email protected]> <[email protected]>
Doxygen は山括弧なしでもリンクを生成することに注意してください。
Doxygen は、特別なリンカーカー [TOC] をサポートしています。これは、ページの先頭にすべてのセクションをリストした目次を生成するためにページに配置できます。
[TOC] を使用することは、\tableofcontents コマンドを使用することと同じであることに注意してください。
TOC_INCLUDE_HEADINGS は0より大きい値に設定する必要があることに注意してください。そうしないと、Markdown ヘッダーを使用しても目次は表示されません。
"Markdown Extra" で定義されている機能の1つは、シンプルなテーブルのサポートです
テーブルは、ヘッダー行、区切り線、および少なくとも1つの行で構成されます。テーブルの列はパイプ (|) 文字で区切られます。
例を次に示します
First Header | Second Header ------------- | ------------- Content Cell | Content Cell Content Cell | Content Cell
これにより、次のテーブルが生成されます
| 最初のヘッダー | 2番目のヘッダー |
|---|---|
| コンテンツセル | コンテンツセル |
| コンテンツセル | コンテンツセル |
列の配置は、ヘッダー区切り線にある1つまたは2つのコロンで制御できます
| Right | Center | Left | | ----: | :----: | :---- | | 10 | 10 | 10 | | 1000 | 1000 | 1000 |
これは次のようになります
| 右 | 中央 | 左 |
|---|---|---|
| 10 | 10 | 10 |
| 1000 | 1000 | 1000 |
さらに、列スパンと行スパンがサポートされています。セルのキャレット ("^") は、上のセルが行をまたがることを示します。任意の数の行スパンにキャレットのシーケンスを使用できます。例
| Right | Center | Left | | ----: | :----: | :---- | | 10 | 10 | 10 | | ^ | 1000 | 1000 |
これは次のようになります
| 右 | 中央 | 左 |
|---|---|---|
| 10 | 10 | 10 |
| 1000 | 1000 |
列スパンは、隣接する垂直バー ("|") を使用してサポートされます。追加の垂直バーごとに、追加の列をまたがることを示します。別の言い方をすれば、単一の垂直バーは単一の列スパンを示し、2つの垂直バーは2列スパンを示し、以下同様です。例
| Right | Center | Left | | ----: | :----: | :---- | | 10 | 10 | 10 | | 1000 |||
これは次のようになります
| 右 | 中央 | 左 |
|---|---|---|
| 10 | 10 | 10 |
| 1000 | ||
Doxygen のより複雑なテーブルについては、テーブルの挿入をご覧ください。
"Markdown Extra" で定義されているもう1つの機能は、フェンス付きコードブロックのサポートです
フェンス付きコードブロックはインデントを必要とせず、「フェンスライン」のペアで定義されます。このような行は、行に3つ以上のチルダ (~) 文字で構成されます。ブロックの終わりも同じ数のチルダを持つ必要があります。例を次に示します
This is a paragraph introducing: ~~~~~~~~~~~~~~~~~~~~~ a one-line code block ~~~~~~~~~~~~~~~~~~~~~
デフォルトでは、出力は通常のコードブロックと同じです。
Doxygen でサポートされている言語の場合、コードブロックを構文強調表示で表示することもできます。そのためには、開始フェンスの後にプログラミング言語に対応する典型的なファイル拡張子を指定する必要があります。例えば、Python 言語に従って強調表示するには、次のように記述する必要があります
~~~~~~~~~~~~~{.py}
# A class
class Dummy:
pass
~~~~~~~~~~~~~
これにより、次が生成されます
C の場合は次のように記述します
~~~~~~~~~~~~~~~{.c}
int func(int a,int b) { return a*b; }
~~~~~~~~~~~~~~~
これにより、次が生成されます
ドットはオプションであり、言語名がアルファベット文字で始まり、それ以降の文字が英数字またはプラス記号である場合、中括弧はオプションです。
フェンス付きコードブロックを示すもう1つの方法は、3つ以上のバックティック (```) を使用することです
画像形式 dot、msc、plantuml の場合、フェンス付きブロックは、画像形式が有効になっている場合 ( HAVE_DOT と PLANTUML_JAR_PATH を参照) は画像として表示され、そうでない場合はプレーンコードとして表示されます。
例
または
標準の Markdown はヘッダーのラベル付けをサポートしていません。これは、セクションにリンクしたい場合に問題となります。
PHP Markdown Extra では、ヘッダーに次を追加することでヘッダーにラベルを付けることができます
Header 1 {#labelid}
========
## Header 2 ## {#labelid2}
同じコメントブロック内のセクションにリンクするには、次を使用できます
[Link text](#labelid)
一般的にセクションにリンクするために、Doxygen では @ref を使用できます
[Link text](@ref labelid)
これはレベル1から4のヘッダーにのみ機能することに注意してください。
標準の Markdown は画像寸法の制御をサポートしていないため、ドキュメント作成時の柔軟性が低下します。
PHP Markdown Extra では、次のように画像にextra属性を追加できます
{attributes}
出力形式固有の属性を可能にするために、次の構文がサポートされています
{format: attributes, format: attributes}
可能な内容については、\image コマンドの サイズ表示の段落を参照してください。
例
{html: width=50%, latex: width=5cm}
Doxygen は可能な限り Markdown 標準に従おうとしますが、いくつかの逸脱と Doxygen 固有の追加があります。
Doxygen は Markdown 書式設定のファイルを処理できます。これには、そのようなファイルの拡張子は .md または .markdown である必要があります (Markdown ファイルの拡張子が異なる場合は EXTENSION_MAPPING を参照し、パーサー名として md を使用してください)。各ファイルはページに変換されます (詳細については page コマンドを参照)。Doxygen は、Markdown ファイルが専用コマンド (\defgroup、\dir など) で始まる場合、ファイルがディレクトリまたはグループドキュメントのみを含む場合に空のページが作成されるのを避けるために、専用ページを作成しません。サブディレクトリ内の README.md ファイルは、専用コマンド (@page、@mainpage など) で新しいページを作成するために明示的に上書きされない限り、ディレクトリドキュメントとして扱われます。
デフォルトでは、ページの名前とタイトルはファイル名から派生します。ただし、ファイルがレベル1ヘッダーで始まる場合、それはページのタイトルとして使用されます。ヘッダー ID 属性に示されているように、ヘッダーにラベルを指定した場合、Doxygen はそれをページ名として使用します。
ラベルが index または mainpage と呼ばれる場合、Doxygen はドキュメントをフロントページ (index.html) に配置します。
Doxygen で処理されるとメインページとして表示される README.md ファイルの例を次に示します
My Main Page {#mainpage}
============
Documentation that will appear on the main page
ページにラベルがある場合、上記のように @ref を使用してそれにリンクできます。そのようなラベルのない Markdown ページを参照するには、単純にページのファイル名を使用できます。例
See [the other page](other.md) for more info.
Markdown はブロックレベルの HTML の処理方法に関してかなり厳格です
ブロックレベルの HTML 要素 (例: <div>、<table>、<pre>、<p> など) は、周囲のコンテンツと空白行で区切られなければならず、ブロックの開始タグと終了タグはタブやスペースでインデントされてはなりません。
Doxygen にはこの要件はなく、そのような HTML ブロック内でも Markdown 書式設定を処理します。唯一の例外は <pre> ブロックであり、これは手付かずで渡されます (アスキーアートに便利です)。
Doxygen は、逐語的ブロックまたはコードブロック内、および変更なしで処理する必要があるその他のセクション (たとえば、数式やインライン dot グラフ) 内では Markdown 書式設定を処理しません。
Markdown は、コードブロックを開始するために単一のタブまたは4つのスペースを許可します。Doxygen は Markdown 処理を行う前にタブをスペースに置き換えるため、設定ファイルの TAB_SIZE が4に設定されている場合にのみ同じ効果が得られます。より高い値に設定されている場合、コードブロックにスペースが存在します。より低い値は、単一のタブがコードブロックの開始として解釈されるのを防ぎます。
Markdown では、4スペースでインデントされた (リスト内では8スペースでインデントされた) ブロックはすべてコードブロックとして扱われます。このインデント量は絶対的、つまり行の開始から数えられます。
Doxygen のコメントはプログラミング言語によって要求される任意のインデントレベルで表示できるため、代わりに相対インデントを使用します。インデント量は、前の段落に対して相対的に数えられます。前の段落がない場合 (つまり、コードブロックで開始したい場合)、コメントブロック全体の最小インデント量が参照として使用されます。
ほとんどの場合、この違いは異なる出力にはなりません。段落のインデントを操作した場合にのみ、違いが顕著になります
text text text code
この場合、Markdown は「code」という単語をコードブロックに配置しますが、Doxygen はそれを通常のテキストとして扱います。これは、絶対インデントが4であっても、前の段落に対するインデントが1に過ぎないためです。
相対インデントを決定するときにリストマーカーは数えられないことに注意してください
1. Item1
More text for item1
2. Item2
Code block for item2
Item1 のインデントは4 (リストマーカーを空白として扱った場合) なので、次の段落「More text...」は同じインデントレベルで始まり、したがってコードブロックとして認識されません。
標準の Markdown や GitHub Flavored Markdown とは異なり、Doxygen は内部のアンダースコア、アスタリスク、チルダに触れないため、以下はそのまま表示されます
a_nice_identifier
さらに、* または _ は、次の条件を満たす場合にのみ強調を開始し、~ は、次の条件を満たす場合にのみ打ち消し線を開始します
強調または打ち消し線は、次の条件を満たす場合に終了します
強調または打ち消し線のスパンは、単一の段落に制限されます。
最後に、C スタイルの Doxygen コメントブロック (つまり /``** ... *``/ ) 内で、行の先頭にアスタリスク * を使用してテキストの一部を強調表示したい場合、先頭に列「ラインアップ」として * がない場合、Doxygen は行の先頭にあるアスタリスクのシーケンスを「ラインアップ」として認識し、強調として認識しないことに注意してください。したがって、以下は太字としてレンダリングされません
/** **this is not bold** */
しかし、これは太字としてレンダリングされます
/** * **this is bold** */
標準の Markdown とは異なり、Doxygen は以下をそのままにしておくことに注意してください。
A `cool' word in a `nice' sentence.
言い換えれば、単一引用符は、バックティックのペアで囲まれたコードスパンの特別な扱いをキャンセルします。この追加の制限は、下位互換性の理由で追加されました。
コードスパン内に単一引用符を使用したい場合は、1つのバックティックではなく、コードスパンの周りに2つのバックティックを使用してください。
二重バックティックも同様に二重引用符で終わります。
A ``cool'' word in a ``nice'' sentence.
Markdown では、空行で区切られた2つのリストが1つのリストに結合されます。これは予期せぬことであり、多くの人がバグだと考えています。しかし、Doxygen は期待どおりに2つの個別のリストを作成します。
例
- Item1 of list 1 - Item2 of list 1 1. Item1 of list 2 2. Item2 of list 2
Markdown では、リストをマークするために使用する実際の数字は、Markdown が生成する HTML 出力に影響しません。つまり、標準の Markdown は以下を3つの番号付き項目を持つ1つのリストとして扱います
1. Item1 1. Item2 1. Item3
しかし、Doxygen はマークとして使用される数字が厳密に昇順であることを要求するため、上記の例では1つの項目を持つ3つのリストが生成されます。前の項目と同じかそれより小さい数字を持つ項目は、新しいリストを開始します。例えば
1. Item1 of list 1 3. Item2 of list 1 2. Item1 of list 2 4. Item2 of list 2
次が生成されます
歴史的に、Doxygen には -# マーカーを使用して番号付きリストを作成する追加の方法があります
-# item1 -# item2
チェック済みまたは未チェックのチェックボックスをインジケーターとするリストは、- [ ] または - [x] または - [X] をマーカーとして使用して作成されます
- [ ] unchecked - [x] checked
コメントブロック内でリストを開始したり、水平線を作成したりするために * を使用する場合は、特別な注意が必要です。
Doxygen は、Markdown 処理を行う前に、コメントから先頭の * をすべて削除します。したがって、以下は正常に機能しますが
/** A list:
* * item1
* * item2
*/
先頭の * を削除すると、Doxygen は他のアスタリスクも削除し、リストが消えてしまいます！
* で作成された水平線は、まったく表示されません。これらは Markdown ファイルでのみ機能します。
はぐれた * または _ が数段落後に何かに一致し、その間のすべてを強調表示してしまうのを避けるため、Doxygen は * と _ のスコープを単一の段落に制限します。
コードスパンの場合、開始バックティックと終了バックティックの間には2つの改行のみが許可されます。
リンクにも制限があります。リンクテキストとリンクタイトルはそれぞれ1つの改行のみを含めることができ、URL には改行を含めることはできません。
GitHub 版の Markdown には、いわゆるアラートのサポートがあります。構文は1レベルのブロッククォートの後に [!<alert>] が続く形式で、<alert> は note、warning、tip、caution、important のいずれかになります。Doxygen では、これらのアラートは通常の Doxygen コマンドに翻訳されます
例
これは次のようにレンダリングされます
Doxygen はソースコードを解析するとき、まずコメントブロックを抽出し、次にこれらを Markdown プリプロセッサに通します。Markdown プリプロセッサの出力は、特殊コマンドと HTML コマンドを含むテキストで構成されます。2回目のパスでは、Markdown プリプロセッサの出力を取得し、それをさまざまな出力形式に変換します。
Markdown プリプロセス中にエラーは生成されません。Markdown 構文に適合しないものはすべてそのまま渡されます。後続の解析フェーズでは、これはエラーにつながる可能性があり、中間形式に基づいているため、常に明らかではない場合があります。
Markdown 処理後の結果を確認するには、-d Markdown オプションを付けて Doxygen を実行します。その後、各コメントブロックが Markdown 処理の前後に表示されます。
1.15.0 で生成