|
latest release v1.8.11 - last update Mon Oct 25 2021 | |
|
目次MarkdownサポートMarkdown サポートは、doxygen version 1.8.0で導入しました。Markdownは、John Gruberが書いたプレーンテキストのフォーマットで、次のような設計目標を基礎としています。
次のセクションで、Markdownの基本機能を簡単に紹介します。 詳しくは、Markdownサイトを参照してください。 あちこちでMarkdownの拡張が行われました。たとえば、PHP Markdown Extraと、GitHub flavored Markdownです。セクション Markdown 拡張 では、doxygenがサポートする拡張を紹介します。 最後に、セクションDoxygen 特有の事項 で、Markdown標準をdoxygenではどのように実装しているかを紹介します。 標準のMarkdown段落Markdownサポートを始める前から、doxygenは同様の段落作法をサポートしていました。段落を作るには、連続するテキスト行を、１行以上の空行で分けてください。 例: ここに一段落目を書きます。 続くテキストを別の段落に書きます。 見出しMarkdown同様、doxygenは２種類の見出しをサポートします。 レベル1か2の見出しは、次のように書きます。 レベル1の見出し ========================= レベル2の見出し ------------------------- 見出しの次行は、=か-だけで構成します。 =、-の正確な数は、2以上あれば、重要ではありません。 または、行の初めに # を使うこともできます。行の初めの数で、レベル(6が最大)を決めます。行の終わりに # をいくつか使うことで見出しを終わることもできます。例: # レベル1の見出し ### レベル3の見出し ####### 引用ブロック引用ブロックの各行の初めには、一つ以上の>を置きます。これは、テキストだけのメールと似ています。 > 引用ブロック > 複数行です 引用ブロック内には、リストとコードブロック(下記参照)を含むことができます。 引用ブロックをネストすることもできます。 doxygenで注意していただきたいのは、>の後にスペースを入れることです。誤検知を避けるためです。 たとえば、次のように書くと、 0 if OK\n >1 if NOK ２行目は引用ブロックになりません。 リスト行頭に -,+,* を書くことで単純なリストを作れます。 - アイテム１ アイテム１のテキスト - アイテム２ + ネストされたリストのアイテム + もうひとつのネストされたアイテム - アイテム３ リストのアイテムは、各段落が適切にインデントされていれば、複数の段落に分けることができます。リストはネストできます。 また、次のように、番号を付けることもできます。 1. 最初にアイテム 2. 次のアイテム doxygen特有の事項については、リストの拡張 を読んでください。 コードブロックフォーマット済み逐語ブロックは、テキストブロックの各行を、最低４つのスペースでインデントすれば、作れます。 ここは普通の段落
ここはコードブロック
再び普通の段落
doxygenは、コードブロックから必須のインデントを削除します。 ここで注意していただきたいのは、コードブロックは段落の途中で始められないことです。コードブロック前の行は空にしてください。 セクション コードブロックのインデント で、doxygenによるインデントの扱い方を細かく説明します。標準のMarkdownとは少し扱いが違うのです。 水平線水平線を作るには、行にハイフンかアスタリスクかアンダースコアを三つ以上入れます。その行には、空白をいくつ含めてもかまいません。 例: - - - ______ コメントブロックにアスタリスクを使用しても水平線にはなりません。詳細はアスタリスクの使用 を参照してください。 強調テキストを強調するには、アンダーラインかアスタリスクでテキストをはさんでください。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 "オプションでタイトル" また、ここでも @ref を使ってイメージへのリンクを定義できます。  ![イメージ定義] [イメージ定義]: @ref image.png "キャプション テキスト" キャプション テキストはオプションです。 自動リンクURL や e-mail アドレスへのリンクを作る際、Markdown は次のシンタックスをサポートします。 <http://www.example.com> <address@example.com> doxygen は、角括弧なしでもリンクを作ることができます。 Markdown 拡張目次doxygen は、特別なリンクマーカー
テーブル"Markdown 拡張" で定義されている機能のうち、simple tables のサポートがあります。 テーブルはヘッダー行、セパレータ行と、一行以上のデータ行からなります。列は、パイプ(|)文字で区切ります。 例: 最初のヘッダ | 次のヘッダ ------------- | ------------- 内容 | 内容 内容 | 内容 以上は、次のテーブルを作ります:
列の並び方を制御するには、ヘッダのセパレータ行にコロンを１つか２つおきます。 | Right | Center | Left | | ----: | :----: | :---- | | 10 | 10 | 10 | | 1000 | 1000 | 1000 | 上の例は次のようになります:
Doxygenで更に複雑なテーブルを見るには、tables を見てください。 仕切り付コードブロック"Markdown 拡張" で定義されている機能のうち、仕切り付コードブロック のサポートがあります。 仕切り付コードブロックでは、インデントがなく、"仕切り行"のペアで定義されます。仕切り行は、3つ以上のチルダ (~) で作ります。ブロックの終わりには同じ数のチルダで行を作ります。例: この段落ではこういった内容を紹介します: ~~~~~~~~~~~~~~~~~~~~~ 1行のコードブロック ~~~~~~~~~~~~~~~~~~~~~ デフォルトの出力は、通常のコードブロックと同じです。 doxygen がサポートしている言語では、コードブロックを強調できます。それには、最初の仕切りの後ろに、言語特有のファイル拡張子を指定します。例えば、Python では、次のように書きます。 ~~~~~~~~~~~~~{.py}
# A class
class Dummy:
pass
~~~~~~~~~~~~~
次のようになります: C 言語では次のように書きます: ~~~~~~~~~~~~~~~{.c}
int func(int a,int b) { return a*b; }
~~~~~~~~~~~~~~~
次のようになります: int func(int a,int b) { return a*b; }
波括弧とドットはオプションです。 仕切りつきコードブロックを示す別の方法では、3つ以上のバックティック(<tt>)を使います。 仕切りつきコードブロック ``` ヘッダ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 フォーマットのファイルを処理できます。 それには、拡張子は デフォルトでは、ページの名前とタイトルは、ファイル名から取ります。しかし、ファイルの始まりがレベル1のヘッダであれば、それがタイトルとなります。ヘッダにラベルをつければ(ヘッダID属性 にあるように)、doxygen はそれをページ名とします。 ラベルが
私のメインページ {#mainpage}
============
メインページの内容に現れるドキュメント
ページにラベルがある場合、@ref を使って上記のように表示できます。ラベルなしでmarkdownページを参照するには、以下のように、単にページのファイル名を使います。 詳しくは、[the other page](other.md) を参照 HTML ブロックの扱いMarkdown では、ブロックレベルHTMLの扱い方が極めて厳格です。
doxygen にはこの制約がなく、また、そのようなHTMLブロック内部のMarkdownフォーマットを処理します。唯一の例外は、 コードブロックのインデントMarkdown では、コードブロックの始めに、単一のタブあるいは4スペースを置けます。 doxygen は、Markdown処理を行う前に、タブをスペースで置き換えてしまいます。設定ファイルでTAB_SIZEを4にしておけば、同じ効果が得られます。しかし、4を超えると、スペースがコードブロックに出現するでしょう。4未満であれば、単一のタブはコードブロックの先頭とは解釈されないでしょう。 Markdown では、4つのスペース(リスト内部では8スペース)はコードブロックとして扱われます。このインデント数は絶対で、行の最初から数えます。 doxygenコメントは、どのインデントレベルでも出現しうる(プログラミング言語で必要)ので、代わりに相対的インデントを使用します。インデントの量は、前段と相対的に数え上げます。 前段がない場合(コードブロックで始めたい場合)には、コメントブロック全体の最小の量をレファレンスとして使用します。 多くの場合、この違いは出力の違いを生み出しません。段落のインデントをいじくった場合のみ、違いが目立ちます。 text text text code この場合、Markdownは code をコードブロックに配置するでしょう。一方、doxygenでは、通常のテキストとして扱います。絶対的なインデントは4でも、前段と相対的に見た場合のインデントはたったの１だからです。 リストマーカーは、相対的インデントを決めるときに数え上げます。 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 は、次のようになります。
歴史的に、doxygenには、 -# item1 -# item2 アスタリスクの使用リストやルーラーを始めるために、コメントブロックにアスタリスクを使うときには、特別な配慮が必要です。 doxygenは、コメントから先頭のアスタリスクを抜いてからmarkdown処理をします。ですので、次のような例はうまくいきます。 /** リスト:
* * アイテム1
* * アイテム2
*/
でも、逆に先頭のアスタリスクを除いてからdoxygenに与えると、他のアスタリスクも抜かれてしまい、リストが消えてしまいます。 アスタリスクで作ったルーラーは、見えなくなります。Markdownファイルでないと見えません。 マークアップ範囲の制限まばらなアスタリスクやアンダースコアは、あとの多くの段落にマッチしてしまい、中間のものを強調してしまったりするので、doxygenでは、アスタリスクやアンダースコアの範囲は、単一の段落に制限しています。 コード範囲については、バッククォートの間に、2行だけ許されています。 リンクにも制限があります。リンクテキストとリンクタイトル、それぞれ一回しか改行できません。URLには改行を入れられません。 問題のデバッグdoxygenは、ソースコードを解析する際、まずコメントブロックを抜き出して、それをMarkdownプリプロセッサに渡します。Markdownプリプロセッサからの出力は、特殊コマンド と HTML コマンド を含むテキストです。2度目のパスはMarkdownプリプロセッサからの出力を受け取り、それをさまざまな出力フォーマットに変換します。 Markdownプリプロセッサの処理では、エラーは出力されません。Markdownシンタックスに適合しないものは、そのまま単純に渡されます。その後の解析フェーズでは、エラーになることもあります。しかし、そのエラーは中間フォーマットに基づいているので、常に明らかとは限りません。 Markdown処理の結果を見るには、 |
|
|
This page was last modified on Mon Oct 25 2021.
© 1997-2021 Dimitri van Heesch, first release 27 oct 1997.
© 2001 OKA Toshiyuki (Japanese translation). © 2006-2021 TSUJI Takahiro (Japanese translation). © 2006-2014 TAKAGI Nobuhisa (Japanese translation). |
