Doxygen latest release v1.8.3.1 - last update Sat Aug 24 2014

Markdownサポート

Markdown サポートは、doxygen version 1.8.0で導入しました。Markdownは、John Gruberが書いたプレーンテキストのフォーマットで、次のような設計目標を基礎としています。

Markdownフォーマットのシンタックスの設計目標は、できる限り読みやすくすることです。 その思想は、Markdownフォーマットの文書は、プレーンテキストのまま印刷可能で、 タグ付けや、フォーマット指示といった様子がないようにすることです。 Markdownシンタックスは、テキストをHTMLに変換する既存のフィルターの影響を受けていますが、 その着想の根本にあるのは、プレーンテキストのメールのフォーマットです。

次のセクションで、Markdownの基本機能を簡単に紹介します。 詳しくは、Markdownサイトを参照してください。

あちこちでMarkdownの拡張が行われました。たとえば、PHP Markdown Extraと、GitHub flavored Markdownです。セクション Markdown 拡張 では、doxygenがサポートする拡張を紹介します。

最後に、セクションDoxygen 特有の事項 で、Markdown標準をdoxygenではどのように実装しているかを紹介します。

標準のMarkdown

段落

Markdownサポートを始める前から、doxygenは同様の段落作法をサポートしていました。段落を作るには、連続するテキスト行を、1行以上の空行で分けてください。

例:

ここに一段落目を書きます。

続くテキストを別の段落に書きます。

見出し

Markdown同様、doxygenは2種類の見出しをサポートします。

レベル1か2の見出しは、次のように書きます。

レベル1の見出し
=========================

レベル2の見出し
-------------------------

見出しの次行は、=か-だけで構成します。 =、-の正確な数は、2以上あれば、重要ではありません。

または、行の初めに # を使うこともできます。行の初めの数で、レベル(6が最大)を決めます。行の終わりに # をいくつか使うことで見出しを終わることもできます。例:

# レベル1の見出し

### レベル3の見出し #######

引用ブロック

引用ブロックの各行の初めには、一つ以上の>を置きます。これは、テキストだけのメールと似ています。

> 引用ブロック
> 複数行です

引用ブロック内には、リストとコードブロック(下記参照)を含むことができます。 引用ブロックをネストすることもできます。

doxygenで注意していただきたいのは、>の後にスペースを入れることです。誤検知を避けるためです。 たとえば、次のように書くと、

0  if OK\n
>1 if NOK

2行目は引用ブロックになりません。

リスト

行頭に -,+,* を書くことで単純なリストを作れます。

- アイテム1

  アイテム1のテキスト

- アイテム2
  + ネストされたリストのアイテム
  + もうひとつのネストされたアイテム
- アイテム3

リストのアイテムは、各段落が適切にインデントされていれば、複数の段落に分けることができます。リストはネストできます。 また、次のように、番号を付けることもできます。

1. 最初にアイテム
2. 次のアイテム

doxygen特有の事項については、リストの拡張 を読んでください。

コードブロック

フォーマット済み逐語ブロックは、テキストブロックの各行を、最低4つのスペースでインデントすれば、作れます。

ここは普通の段落

    ここはコードブロック

再び普通の段落

doxygenは、コードブロックから必須のインデントを削除します。 ここで注意していただきたいのは、コードブロックは段落の途中で始められないことです。コードブロック前の行は空にしてください。

セクション コードブロックのインデント で、doxygenによるインデントの扱い方を細かく説明します。標準のMarkdownとは少し扱いが違うのです。

水平線

水平線を作るには、行にハイフンかアスタリスクかアンダースコアを三つ以上入れます。その行には、空白をいくつ含めてもかまいません。

例:

- - -
______

コメントブロックにアスタリスクを使用しても水平線にはなりません。詳細はアスタリスクの使用 を参照してください。

強調

テキストを強調するには、アンダーラインかアスタリスクでテキストをはさんでください。2つ使うと、さらに強くできます。

例:

 アスタリスク一つ*

_アンダーライン一つ_

  アスタリスク2つ**

__アンダーライン2つ__

セクション 強調の限界 で、doxygenの強調の扱い方が、標準のMarkdownと少し違うところを説明します。

コード範囲

コード範囲を示すには、コードをバッククォート(`)で囲みます。コードブロックと違い、コード範囲は段落の中に出現します。例えば、

`printf()` 関数を使いなさい

コード範囲内で文字バッククォートを使うには、次のようにします。

コマンド `ls` の出力先を `var` に指定するには、 ``var=`ls``` とします。

セクション コード範囲の制限 で、doxygenのコード範囲の扱い方が、標準のMarkdownと少し違うところを説明します。

リンク

doxygenでは、 *インライン* と *参照* どちらのリンクスタイルも使えます。

どちらのスタイルでも、リンク定義は、[角括弧] で区切られたリンクテキストで始まります。

インラインリンク

インラインリンクでは、リンクテキストの後 URL が続き、その次にリンクタイトルがオプションで続きます。これら2つは、通常の括弧で囲まれます。 リンクタイトル自体は、引用符で囲まれます。

例:

[リンクテキスト](http://example.net/)
[リンクテキスト](http://example.net/ "リンクタイトル")
[リンクテキスト](/relative/path/to/index.html "リンクタイトル") 
[リンクテキスト](somefile.html) 

加えて、doxygenは、文書つき要素をリンクする方法も提供します。

[リンクテキスト](@ref MyClass) 

参照リンク

URL をインラインに配置せず、リンクを分離して、テキスト内部から参照するようにもできます。

リンク定義は次のようにします。

[リンク名]: http://www.example.com "オプションでタイトル"

二重引用符でなく、一重引用符や括弧もタイトル部分に使えます。

一度定義すると、リンクは次のようになります。

[リンクテキスト][リンク名]

リンクテキストと名が同じなら、次のようにできます。

[リンク名][]

あるいは

[リンク名]

でリンクへの参照を定義できます。

リンク名の適合は、大文字小文字を区別しません。 例:

[Google] からのトラフィック量は、[Yahoo] や [MSN] の10倍ある。

[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 では、イメージへのシンタックスはリンクと似ています。 唯一の違いは、リンクテキストの前に ! を置くことです。

例:

![キャプション テキスト](/path/to/img.jpg)
![キャプション テキスト](/path/to/img.jpg "イメージタイトル")
![キャプション テキスト][イメージ定義]
![イメージ定義]

[イメージ定義]: /path/to/img.jpg "オプションでタイトル"

また、ここでも @ref を使ってイメージへのリンクを定義できます。

![キャプション テキスト](@ref image.png)
![イメージ定義]

[イメージ定義]: @ref image.png "キャプション テキスト"

キャプション テキストはオプションです。

自動リンク

URL や e-mail アドレスへのリンクを作る際、Markdown は次のシンタックスをサポートします。

<http://www.example.com>
<address@example.com>

doxygen は、角括弧なしでもリンクを作ることができます。

Markdown 拡張

目次

doxygen は、特別なリンクマーカー [TOC] をサポートします。ページの先頭に全セクションを並べる目次を作るために配置します。

[TOC] は、\tableofcontents コマンドと同義です。

テーブル

"Markdown 拡張" で定義されている機能のうち、simple tables のサポートがあります。

テーブルはヘッダー行、セパレータ行と、一行以上のデータ行からなります。列は、パイプ(|)文字で区切ります。

例:

最初のヘッダ  | 次のヘッダ
------------- | -------------
内容          | 内容 
内容          | 内容 

以上は、次のテーブルを作ります:

最初のヘッダ 次のヘッダ
内容 内容
内容 内容

列の並び方を制御するには、ヘッダのセパレータ行にコロンを1つか2つおきます。

| Right | Center | Left  |
| ----: | :----: | :---- |
| 10    | 10     | 10    |
| 1000  | 1000   | 1000  |

上の例は次のようになります:

Right Center Left
10 10 10
1000 1000 1000

仕切り付コードブロック

"Markdown 拡張" で定義されている機能のうち、仕切り付コードブロック のサポートがあります。

仕切り付コードブロックでは、インデントがなく、"仕切り行"のペアで定義されます。仕切り行は、3つ以上のチルダ (~) で作ります。ブロックの終わりには同じ数のチルダで行を作ります。例:

この段落ではこういった内容を紹介します:

~~~~~~~~~~~~~~~~~~~~~
1行のコードブロック
~~~~~~~~~~~~~~~~~~~~~

デフォルトの出力は、通常のコードブロックと同じです。

doxygen がサポートしている言語では、コードブロックを強調できます。それには、最初の仕切りの後ろに、言語特有のファイル拡張子を指定します。例えば、Python では、次のように書きます。

~~~~~~~~~~~~~{.py}
# A class
class Dummy:
    pass
~~~~~~~~~~~~~

次のようになります:

1 # A class
2 class Dummy:
3  pass

C 言語では次のように書きます:

~~~~~~~~~~~~~~~{.c}
int func(int a,int b) { return a*b; }
~~~~~~~~~~~~~~~

次のようになります:

int func(int a,int b) { return a*b; }

波括弧とドットはオプションです。

ヘッダID属性

標準 Markdown では、ヘッダにラベル付けできません。ですので、セクションへのリンクをしたい場合に問題となります。

PHP Markdown Extra では、次のようにすることでヘッダにラベル付けできます。

ヘッダ 1                {#ラベル id 1}
========

## ヘッダ 2 ##          {#ラベル id 2}

同じコメントブロックでセクションへリンクするには、次のようにします。

[リンクテキスト](#ラベル id)

一般にセクションへリンクするには、doxygen では @ref を使えます。

[リンクテキスト](@ref ラベル id)

注意: レベル1~4のヘッダにしか対応しません。

Doxygen 特有の事項

doxygen でも Markdown のスタンダードに従うよう努力していますが、少し逸脱やdoxygen特有の追加があります。

Markdown ファイルをページとして含める

doxygen は、Markdown フォーマットのファイルを処理できます。 それには、拡張子は .md.markdown にします(ファイルの拡張子がこれと違っていたらEXTENSION_MAPPING を見て、パーサーの名前に md を使ってください)。各ファイルは、ページに変換されます(詳細は、page コマンドを見てください)。

デフォルトでは、ページの名前とタイトルは、ファイル名から取ります。しかし、ファイルの始まりがレベル1のヘッダであれば、それがタイトルとなります。ヘッダにラベルをつければ(ヘッダID属性 にあるように)、doxygen はそれをページ名とします。

ラベルが indexmainpage であれば、doxygen はそのドキュメントをインデックスページ(index.html)とします。

README.md の例を示します。doxygen が処理するとメインページになります。

私のメインページ                         {#mainpage}
============

メインページの内容に現れるドキュメント

HTML ブロックの扱い

Markdown では、ブロックレベルHTMLの扱い方が極めて厳格です。

ブロックレベルHTMLの要素 <div>, <table>, <pre>, <p>, など は、周囲の内容から、空行で分離しなければならず、 ブロックのはじめと終わりのタグは、タブやスペースでインデントしてはいけません。

doxygen にはこの制約がなく、また、そのようなHTMLブロック内部のMarkdownフォーマットを処理します。唯一の例外は、<pre> ブロックで、そのままと残ります(ASCII風では便利)。
逐語ブロックやコードブロック内部、そして変更なしに処理すべきほかのセクション(例えば、式やインラインドットグラフ)では、doxygen は Markdown フォーマットを処理しません。

コードブロックのインデント

Markdown では、コードブロックの始めに、単一のタブあるいは4スペースを置けます。 doxygen は、Markdown処理を行う前に、タブをスペースで置き換えてしまいます。設定ファイルでTAB_SIZEを4にしておけば、同じ効果が得られます。しかし、4を超えると、スペースがコードブロックに出現するでしょう。4未満であれば、単一のタブはコードブロックの先頭とは解釈されないでしょう。

Markdown では、4つのスペース(リスト内部では8スペース)はコードブロックとして扱われます。このインデント数は絶対で、行の最初から数えます。

doxygenコメントは、どのインデントレベルでも出現しうる(プログラミング言語で必要)ので、代わりに相対的インデントを使用します。インデントの量は、前段と相対的に数え上げます。 前段がない場合(コードブロックで始めたい場合)には、コメントブロック全体の最小の量をレファレンスとして使用します。

多くの場合、この違いは出力の違いを生み出しません。段落のインデントをいじくった場合のみ、違いが目立ちます。

text

 text

  text

   code

この場合、Markdownは code をコードブロックに配置するでしょう。一方、doxygenでは、通常のテキストとして扱います。絶対的なインデントは4でも、前段と相対的に見た場合のインデントはたったの1だからです。

リストマーカーは、相対的インデントを決めるときに数え上げます。

1.  Item1

    item1のテキスト

2.  Item2

        item2の相対テキスト

Item1ではインデントが4(リストマーカーを空白として扱うとき)なので、次の段落"item1のテキスト"は、同じインデントレベルで始まるのでコードブロックとしての扱いは受けません。

強調の限界

標準のMarkdownとは違い、doxygenは内部のアンダースコアやアスタリスクを処理しません。したがって、次の行はそのまま出現します。

a_nice_identifier

さらに、*_ が強調の始まりとなるのは、次の場合のみです。その次に英数字が続き、しかもスペースや空行、<{([,:; のうちどれかが前置きされた場合。

強調の終わりとなるのは、英数字が続かず、しかもスペースや空行、あるいは({[<=+-\@ のうちどれかが前置きされない場合です。

最後に、強調の範囲は単一の段落に限ります。

コード範囲の制限

標準のMarkdownと違い、doxygenは次の内容を変えません。

`nice' センテンスの `cool' 

つまりは、単一の引用符は、バッククォートのペアに囲まれたコード範囲を特別扱いさせないようにしてしまいます。この特別な制限は、上位互換のために加えられました。

リストの拡張

Markdownでは、空行で区切られた2つのリストは、単一のリストに結合されます。しかし、これはむしろ意外で、多くの人はバグだと考えます。しかし、doxygenは期待通り、2つの分離したリストを作ります。

例:

- リスト 1のアイテム1
- リスト 1のアイテム2

1. リスト 2のアイテム1
2. リスト 2のアイテム2

Markdownではリストをマークするのにあなたが数字を使っても、Markdownが作るHTML出力では効果がありません。つまり、標準のMarkdownは次の行を、3つの番号付アイテムがある、一つのリストとして扱います。

1. Item1
1. Item2
1. Item3

しかし、doxygenでは、番号をマークとして使う場合、昇順でなければならないので、上の例では、一つのアイテムがある3つのリストができます。前のアイテムの番号以下のアイテムは、新しいリストの初めとなります。例えば、

1. Item1 of list 1
3. Item2 of list 1
2. Item1 of list 2
4. Item2 of list 2

は、次のようになります。

  1. Item1 of list 1
  2. Item2 of list 1
  1. Item1 of list 2
  2. Item2 of list 2

歴史的に、doxygenには、-# マーカーを使った番号付リストを作る追加の方法があります。例えば、次のように。

-# item1
-# item2

アスタリスクの使用

リストやルーラーを始めるために、コメントブロックにアスタリスクを使うときには、特別な配慮が必要です。

doxygenは、コメントから先頭のアスタリスクを抜いてからmarkdown処理をします。ですので、次のような例はうまくいきます。

    /** リスト:
     *  * アイテム1
     *  * アイテム2
     */

でも、逆に先頭のアスタリスクを除いてからdoxygenに与えると、他のアスタリスクも抜かれてしまい、リストが消えてしまいます。

アスタリスクで作ったルーラーは、見えなくなります。Markdownファイルでないと見えません。

マークアップ範囲の制限

まばらなアスタリスクやアンダースコアは、あとの多くの段落にマッチしてしまい、中間のものを強調してしまったりするので、doxygenでは、アスタリスクやアンダースコアの範囲は、単一の段落に制限しています。

コード範囲については、バッククォートの間に、2行だけ許されています。

リンクにも制限があります。リンクテキストとリンクタイトル、それぞれ一回しか改行できません。URLには改行を入れられません。

問題のデバッグ

doxygenは、ソースコードを解析する際、まずコメントブロックを抜き出して、それをMarkdownプリプロセッサに渡します。Markdownプリプロセッサからの出力は、特殊コマンドHTML コマンド を含むテキストです。2度目のパスはMarkdownプリプロセッサからの出力を受け取り、それをさまざまな出力フォーマットに変換します。

Markdownプリプロセッサの処理では、エラーは出力されません。Markdownシンタックスに適合しないものは、そのまま単純に渡されます。その後の解析フェーズでは、エラーになることもあります。しかし、そのエラーは中間フォーマットに基づいているので、常に明らかとは限りません。

Markdown処理の結果を見るには、-d Markdown オプションをつけてdoxygenを走らせます。すると、処理の前後に各コメントブロックを書き出します。

のセクションに行く / インデックス に戻る

This page was last modified on Sat Aug 24 2014.
© 1997-2014 Dimitri van Heesch, first release 27 oct 1997.
© 2001 OKA Toshiyuki (Japanese translation).
© 2006-2014 TSUJI Takahiro (Japanese translation).
© 2006-2014 TAKAGI Nobuhisa (Japanese translation).