Menu

言語リファレンス

table of contents

英語版
このページの英語版を見る

ドキュメンテーションジェネレータ

内容
  1. 仕様
    1. 処理の段階
    2. 語(ご)彙(い)
    3. 構文解析
    4. セクション
    5. 標準セクション
    6. 特殊セクション
  2. ハイライト
    1. 埋め込みコメント
    2. 埋め込みコード
    3. インラインコード
    4. 埋め込みHTML
    5. 見出し
    6. リンク
    7. リスト
    8. 表
    9. 引用
    10. 水平ルール
    11. テキストの強調
    12. 識別子の強調
    13. 文字エンティティ
    14. 句読点エスケープ
    15. 文書なし
  3. マクロ
    1. マクロ引数
    2. マクロ定義
    3. 定義済みマクロ
    4. sc.ini のDDOCFILEからのマクロ定義
    5. コマンドラインの.ddocファイルからのマクロ定義
    6. Ddocによって生成されたマクロ定義
  4. ユニットテストからサンプルを生成するためにDdocを使う
  5. Ddocを他のドキュメントに使う
  6. セキュリティに関する考察
  7. Dドキュメント・ジェネレーターへのリンク

Dプログラミング言語では、契約とテストの両方を埋め込むことができる。 コードを埋め込むことができる。 D言語は、コントラクトとテストコードの両方を実際のコードと一緒に埋め込むことができる。ひとつ欠けているのはドキュメントだ、 通常のコメントは、自動抽出やマニュアル・ページへの書式設定には不向きだからだ。 というのも、通常のコメントは、マニュアルページへの自動抽出やフォーマットには通常適さないからだ。 ユーザー・ドキュメントをソースコードに埋め込むことは、重要な利点がある。 ユーザー・ドキュメントをソース・コードに埋め込むことには、ドキュメントを二度書く必要がない、といった重要な利点がある。 ドキュメントがコードと一貫性を保つ可能性がある。

これに対する既存のアプローチには、次のようなものがある:

埋め込みドキュメントに関するDの目標は以下の通りである:

  1. 埋め込み文書としての見栄えである。 としてだけでなく、埋め込まれた文書としても見栄えがする。
  2. 書くのが簡単で自然である、 つまり、<タグ>やその他の不器用な形式への依存が最小限である。 つまり、<タグ>や、完成した文書では決して見ることのないような不格好な形式への依存を最小限にする。
  3. コンパイラがコードを解析してすでに知っている情報を繰り返さない。 コードを解析してコンパイラがすでに知っている情報を繰り返さない。
  4. 埋め込みHTMLに頼らない。 他の目的のための抽出や整形を妨げるからだ。
  5. 既存のDコメントフォームに基づいている。 Dコードにしか興味のないパーサーからは完全に独立している。
  6. 見た目はコードとは違うので、視覚的にコードと混同されることはない。 コードと視覚的に混同されない。
  7. ユーザーが望むなら、Doxygenや他の ドキュメンテーション・エクストラクターを使用できるようにする。

仕様

埋め込み文書コメントの形式に関する仕様は、コンパイラにどのように情報を提示するかを規定するものである。 は、コンパイラにどのように情報を表示するかを規定している。 その情報がどのように使用され、最終的にどのような形で表示されるかは、処理系で定義される。 である。最終的な表示形式が 最終的な表示形式がHTMLウェブ・ページなのか、マニュアル・ページなのか、PDFファイルなのか、などは Dプログラミング言語 "の一部として規定されているわけではない。

処理のフェーズ

埋め込まれたドキュメントのコメントは、一連のフェーズで処理される:

  1. 語(ご)彙(い) - ドキュメントコメントが識別され、トークンに付加される。 トークンに付けられる。
  2. 構文解析 - ドキュメントコメントが特定の宣言に関連付けられ、組み合わされる。 特定の宣言と組み合わされる。
  3. セクション - それぞれのドキュメント・コメントは セクションに分割される。
  4. 特殊なセクションは処理される。
  5. 特殊でないセクションはハイライトされる。
  6. モジュールのすべてのセクションが結合される。
  7. マクロとエスケープテキストの置換が実行され、最終結果が生成される。

語(ご)彙(い)

埋め込まれた文書コメントは、以下のいずれかの形式である:

  1. /** ...*開口部の後の2つの*は、//である。
  2. /++ ...+/冒頭の後の2つの+/ /// 3つのスラッシュ
  3. ///3つのスラッシュ

以下はすべて埋め込み文書コメントである:

/// これは1行の文書化コメントである。

/** これもそうだ。 */

/++ そしてこれだ。 +/

/**
   これは簡単な文書コメントである。
 */

/**
 * この行の先頭の*は、文書コメントの一部ではない。
 */

/*********************************
   /**の直後の余分な*は、
   ドキュメント・コメントの一部ではない。
 */

/++
   これは簡単な文書コメントである。
 +/

/++
 + この行の先頭の+は、文書コメントの一部ではない。
 +/

/+++++++++++++++++++++++++++++++++
   / ++の直後の余分な+は、
   ドキュメントのコメントの一部ではない。
 +/

/**************** 閉じた*は一部ではない *****************/

コメントの冒頭、末尾、左マージンにある余分な*や+は無視される。 は無視され 埋め込まれたドキュメントの一部ではない。 これらのフォームのいずれかに従わないコメントは、ドキュメントコメントではない。

解析

各ドキュメント・コメントは宣言と関連付けられる。 ドキュメント・コメントがそれ自体で1行にあるか、左側に空白だけがある場合 がある場合は、次の 宣言を参照する。 同じ宣言に適用される複数の文書コメントは は連結される。 宣言に関連しない文書コメントは無視される。 ModuleDeclarationの前にあるドキュメント・コメントは、モジュール全体に適用される。 モジュール全体に適用される。 宣言の右側の同じ行に文書化コメントがある場合、それはその宣言に適用される。 宣言の右側の同じ行にある場合は、その宣言に適用される。

宣言の文書コメントが 識別子ditto だけで構成されている場合、同じ宣言スコープにある前の宣言の文書化コメントは、この宣言にも適用される。 宣言スコープの前の宣言の文書化コメントが、この宣言にも適用される。

宣言に対する文書コメントがない場合、その宣言は出力に現れない。 は出力に現れないかもしれない。確実に出力に現れるようにするには その宣言に空の宣言コメントを付ける。 

int a;  /// aのドキュメント; bにはドキュメントがない。
int b;

/** cとdに関する文書 */
/** cとdのドキュメントを増やす */
int c;
/** ditto */
int d;

/** eとfのドキュメント */ int e;
int f;  /// ditto

/** gに関する文書 */
int g; /// gのドキュメントを増やす。

/// CとDのドキュメント
class C
{
    int x; /// C.xのドキュメント

    /** C.yとC.zに関する文書 */
    int y;
    int z; /// ditto
}

/// ditto
class D { }

セクション

文書コメントは一連のセクションである。 セクションとは、その行の空白でない最初の文字で、その直後に':'が続く名前である。 である。この名前がセクション名を形成する。 セクション名は大文字と小文字を区別しない。

http://」や「https://」で始まるセクション名は、セクション名として認識されない。

概要

最初のセクションは「要約」であり、セクション名はない。 最初の段落、空白行またはセクション名までとする。 要約はどのような長さでも構わないが、なるべく1行にまとめること。 要約セクションは任意である。

説明

次の無名のセクションは「説明」である。 これは要約に続く、セクション名に出会うまで、あるいはコメントの終わりまでのすべての段落で構成される。 に続くすべての段落から構成される。

説明セクションは任意である、 サマリーセクションのない説明文はありえない。 

/***********************************
 * myfuncが何をするのかを簡単に要約し、
 * 要約セクションを形成する。
 *
 * シノプシス記述の最初の段落。
 *
 * シノプシス記述の
 * 第2段落。
 */

void myfunc() { }

名前の付いたセクションは、「概要」と「説明」の名前の付いていないセクションに続く。

標準セクション

一貫性と予測可能性のために、いくつかの標準セクションがある。 いずれも存在する必要はない。

Authors:
宣言の作者を列挙する。
/**
 * Authors: Melvin D. Nerd, melvin@mailinator.com
 */
Bugs:
既知のバグを列挙する。
/**
 * Bugs: 負の値では機能しない。
 */
Date:
現在のリビジョンの日付を指定する。日付は で解析可能な形式でなければならない。
/**
 * Date: March 14, 2003
 */
Deprecated:
関連する宣言が非推奨とマークされた場合の説明と対処法を示す。 宣言が非推奨とマークされた場合の説明と対処法を示す。
/**
 * Deprecated: 関数bar()に取って代わられた。
 */

deprecated void foo() { ... }
Examples:
どのような使用例でもよい。
/**
 * Examples:
 * --------------------
 * writeln("3"); // 標準出力に'3'を書き込む
 * --------------------
 */
History:
改訂履歴。
/**
 * History:
 *      V1は初期バージョンである
 *
 *      V2で機能Xを追加した
 */
License:
著作権で保護されたコードのライセンス情報。
/**
 * License: どのような目的にも自由に使用できる
 */

void bar() { ... }
Returns:
関数の戻り値の説明。 もし関数がvoid を返すなら、冗長な文書化はしないこと。
/**
 * ファイルを読む。
 * Returns: ファイルの内容。
 */

void[] readFile(const(char)[] filename) { ... }
See_Also:
他のシンボルのリストと関連項目へのURL。
/**
 * See_Also:
 *    foo, bar, http://www.digitalmars.com/d/phobos/index.html
 */
Standards:
この宣言が特定の規格に準拠している場合は、その説明をここに記述する、 その説明をここに記述する。
/**
 * Standards: DSPEC-1234に準拠
 */
Throws:
スローされる例外と、それがどのような状況でスローされるかを列挙する。
/**
 * ファイルを書き込む。
 * Throws: 失敗するとWriteExceptionが発生する。
 */

void writeFile(string filename) { ... }
Version:
宣言の現在のバージョンを指定する。
/**
 * Version: 1.6a
 */

特別セクション

いくつかのセクションは特殊な意味と構文を持っている。

Copyright:
これは著作権表示を含む。マクロCOPYRIGHTは にセットされる。 著作権セクションは、それがモジュール宣言のためのものであるときだけ、この特別な扱いを受ける。 であるときだけ、この特別な扱いを受ける。
/** Copyright: Public Domain */

module foo;
Params:
関数パラメータは、paramsセクションに列挙することで文書化することができる。 セクションに列挙することで文書化できる。識別子で始まり、その後に で始まる各行は、新しいパラメータの説明を始める。記述は は複数行にまたがることができる。
/***********************************
 * fooはこうしている。
 * Params:
 *      x =     is for this
 *              and not for that
 *      y =     is for that
 */

void foo(int x, int y)
{
}
Macros:
マクロセクションは、Params: セクションと同じ構文に従う。 一連のNAME= 値のペアである。 NAMEはマクロ名、valueは置換テキストである。 テキストである。
/**
 * Macros:
 *      FOO =   今こそ、すべての善人のための
 *              時である
 *      BAR =   bar
 *      MAGENTA =   <font color="magenta">$0</font>
 */

ハイライト

埋め込みコメント

ドキュメントのコメントは (DDOC_COMMENT comment text) 構文を使うことができる。これらのコメントは ネストしない。

埋め込みコード

Dコードは、少なくとも3つのハイフン- で始まる行を使って埋め込むことができる、 バックティック` またはチルダ~ (空白は無視する)で始まる行を使用して、コードのセクションを区切ることができる。 でコードセクションを区切る: 

/++
 + 我々の関数だ。
 +
 + Example:
 + ---
 + import std.stdio;
 +
 + void foo()
 + {
 +     writeln("foo!");  /* 文字列を表示する */
 + }
 + ---
 +/

上記の例では、ドキュメントのコメントに /++ ... +/ を使うことができる。 */ を使うことができる。 を使用できる。

Dコードは自動的にシンタックスハイライトされる。他の言語のコードを含めるには シンタックスハイライトなしで他の言語のコードを含めるには、最初の区切り行の最後に言語文字列を追加する を追加する: 

/++
 + C++の一部
 + ``` cpp
 + #include <iostream>
 +
 + void foo()
 + {
 +     std::cout << "foo!";
 + }
 + ```
 +/

インラインコード

インライン・コードは、GitHubやRedit、Stack Overflow、そしてウェブサイトで使われている構文と同じように、バックティック文字 (`) の間に書くことができる。 GithHub、Reddit、Stack Overflow、その他のウェブサイトで使われている構文と同じだ。開閉文字 この動作をさせるには、オープニング文字とクロージング文字(` )の両方が同じ行になければならない。 の動作を引き起こす。 マクロはバックティック内でも展開される。以下も参照のこと。 エスケープする。

これらのセクション内のテキストは、前述の規則に従ってエスケープされる、 され、$(DDOC_BACKQUOTED) マクロでラップされる。デフォルトでは、このマクロは に展開され、コードとしてフォーマットされたインライン・テキスト・スパンとして表示される。

リテラルバックティック文字は、1行の非ペア` として出力することもできるし、 マクロを使って出力することもできる。 として出力するか、$(BACKTICK) マクロを使って出力することができる。 

 /// `a == b`なら`true`を返却する。
 void foo() {}

 /// バッククォートされた`<html>`が埋め込まれたHTMLとして渡される代わりにユーザーに表示される。
 /// 埋め込みHTMLとして渡される(下記参照)。
 void bar() {}

埋め込みHTML

ドキュメントのコメントにHTMLを埋め込むことができる。 そのままHTML出力に渡される。 しかし、HTMLが埋め込まれたドキュメント・コメント抽出ツールの出力形式になるとは限らない。 しかし、HTMLが埋め込まれたドキュメント・コメント抽出器の望ましい出力形式であるとは限らないので を使うのは避けた方がよい。 

/**
 * 埋め込みHTMLの例:
 *
 * <ol>
 *   <li><a href="http://www.digitalmars.com">Digital Mars</a></li>
 *   <li><a href="http://www.classicempire.com">Empire</a></li>
 * </ol>
 */

見出し

長い文書セクションは、見出しを追加することで細分化することができる。見出しとは 1文字から6文字の# 、空白が続く。 と見出しテキストが続く。# の文字数で見出しのレベルが決まる。 レベルを決定する。見出しは、オプションで、任意の数の末尾の# 文字で終わることができる。 

/**
 * # H1
 * ## H2
 * ### H3
 * #### H4 ###
 * ##### H5 ##
 * ###### H6 #
 */

リンク

ドキュメントは、他のドキュメントやURLにリンクすることができる。リンクには4つのスタイルがある。 のスタイルがある: 

/**
 * いくつかのリンク:
 *
 * 1. [参照リンク][ref] とむき出しの参考リンク: [ref] または [Object]
 * 2. [インラインリンク](https://dlang.org)
 * 3. むき出しのURL: https://dlang.org
 * 4. ![画像](https://dlang.org/images/d3.png)
 *
 * [ref]: https://dlang.org "D言語のウェブサイト"
 */

参考リンク

参照スタイルのリンクは、参照ラベルを角括弧で囲む。リンクの前に オプションで、リンクテキストの前に、同じく角括弧で囲むこともできる。

参照ラベルは、他の場所で定義された参照と一致しなければならない。これは、文書化されるソースコードの範囲内にあるD [Object] シンボルであるかもしれない。 これは、上の例の のように、文書化されるソースコードの範囲内のDシンボルである場合もあれば、同じ文書コメントで定義された明示的な参照である場合もある。 上の例の[ref] のように、同じドキュメント・コメントで定義されている明示的な参照である場合もある。例: この例では、 の項目は、 の項目は、 の項目は、 の項目である。 [ref] の両方のインスタンスは、1. の下部にある一致する定義から、URL とタイトルテキストに置き換えられる。 に置き換えられる。最初のリンクは はreference link 、2番目はref となる。

参照定義は、角括弧内のラベルで始まり、コロン、URL、一重引用符または二重引用符で括られたオプションのタイトルが続く。 コロン、URL、そして一重引用符または二重引用符でくくられたオプションのタイトル、または括弧でくくられた または括弧で囲む。参照ラベルがD記号と参照定義の両方にマッチする場合は、参照定義が使われる。 にマッチする場合は、参照定義が使われる。

生成されるDシンボルへのリンクは、ドキュメント化されるモジュールとルート・パッケージが同じであれば相対リンクとなる。 を持つ場合は相対リンクである。そうでない場合は、URLの前に $(DDOC_ROOT_pkg) マクロが付加される。pkg はリンク先のシンボル のルートパッケージである。Dシンボルへのリンクは、モジュール名の後に$(DOC_EXTENSION) マクロで生成される。そうすると、上の例の[Object] の生成されたURLは、あたかも次のように書かれたかのようになる。 の生成URLは、あたかもそれが書かれたかのようになる: 

$(DOC_ROOT_object)object$(DOC_EXTENSION)#.Object

DOC_ROOT_ マクロ・セクションを使って、外部パッケージ マクロを定義することができる。

インラインリンク

インラインスタイルのリンクは、リンクテキストを角括弧で、リンクURLを括弧で囲む。 で囲む。参照リンクのように、URLの後にタイトル テキストを一重引用符または二重引用符で囲むか、括弧で囲む: 

/// [タイトルテキスト付きリンク](https://dlang.org 'タイトルテキスト')

nakedのURL

ベアURLとは、http:// またはhttps:// で始まる文字列のことである、 で始まり、英字、数字、ピリオドを少なくとも1つ含む文字列である。 -_?=%&/+#~.で始まり、少なくとも1つのピリオドを含む。 URLの認識は、すべてのマクロテキスト置換の前に行われる。 URLは$(DDOC_LINK_AUTODETECT) マクロでラップされる。 はそのままにされる。

画像

画像は参照リンクやインラインリンクと同じ形式だが、最初の角括弧の前に感嘆符 ! を加える。通常のリンクでは のリンクテキストが画像のaltテキストとして使われる。

リスト

文書にはリストが含まれることがある。順序付きリストは、番号の後にピリオド ピリオドで始める: 

/**
 * 1. まずこれだ
 * 2. それなら、これは
 *    1. 下位項目
 */

順序なしリストは、ハイフン(- )、アスタリスク(* )、プラス(+ )で始める。 同じリスト内の後続の項目も同じ記号で始めなければならない: 

/**
 * - リスト
 * - 第2のアイテム
 *
 * + 別のリスト
 *   - サブ項目を持つ
 *
 * * 第三のリスト (2重のアスタリスクに注意)
 */

上の例では二重のアスタリスクがあることに注釈: 」。これは、リストが リストがアスタリスクで区切られた文書コメントの中にあるからである。 はリスト項目ではなく、文書コメントの一部とみなされる。これは 他の行がアスタリスクで始まらない場合でも同様である: 

/**
 - リスト
 * アスタリスクは文書コメントの一部なので、リストではない
 */

/++
 + + このcaveatは、プラス区切りの文書コメントにも適用される
 +/

リスト・アイテムは、新しい段落、見出し、埋め込みコード、または子リスト・アイテムのようなコンテンツを含むことができる。 子リスト項目を含むことができる。単純に、テキストのインデントと同じになるようにコンテンツをインデントする のインデントと同じにする: 

/**
 * - 親リスト項目
 *
 *   の第2段落
 *
 *   - サブ項目
 *     ---
 *     // サブ項目内のコード例
 *     ---
 */

テーブル

データはテーブルに入れることができる。テーブルは、1つのヘッダー行、1つの区切り行、そして0個以上のデータ行で構成される。 区切り行、そして0個以上のデータ行で構成される。各行のセルは パイプ (|) 文字で区切られる。先頭と末尾の|'はオプションである。区切り行の 区切り行のセル数は、ヘッダー行のセル数と一致しなければならない: 

/**
 *  | Item | Price |
 *  | ---- | ----: |
 *  | Wigs | $10 |
 *    Wheels | $13
 *  | Widgets | $200 |
 */

区切り行のセルには、ハイフン(-)とオプションのコロン(:)が含まれる。 ハイフンの左に: を置くと左揃えの列になり、ハイフンの右に: を置くと右揃えの列になる(上の例のように)。 ハイフンの右側は右揃えの列を作る(上の例のように)、 ハイフンの両側に:'sを付けると、中央揃えの列になる。

引用

文書では、引用部分の各行の先頭に を付けることで、引用部分を含めることができる。 >引用には、見出し、リスト、埋め込みコードなどが含まれる。 

/**
 * > To D, or not to D. -- Willeam NerdSpeare
 */

引用行に直接続くテキスト行は、引用の一部とみなされる: 

/**
 * > このライン
 * とこの行はどちらも引用の一部である
 *
 * この行は引用の一部ではない。
 */

水平ルール

3つ以上のアスタリスクを含む行を追加して水平ルールを作成する、 アンダースコアまたはハイフンを含む行を追加する: 

/**
 * ***
 * ___
 */

リストと同様、上の例の最初の* は、区切られた文書コメントの一部であるため、取り除かれる。 が取り除かれることに注意してほしい。 アスタリスクで区切られている。少なくとも3つのアスタリスクが必要である。

ハイフンによる水平ルールを作成するには、ハイフンとハイフンの間にスペースを追加する。 スペースがなければ、埋め込まれたコードブロックの開始または終了として扱われる。どのような水平罫線にも、次のような空白を含めることができる。 を含むことができる: 

/**
 * - - -
 * _ _ _
 * * * *
 */

テキストの強調

アスタリスク (*) で囲まれたテキストは強調され、2つのアスタリスク ( ) で囲まれたテキストは強く強調される。 **で囲まれたテキストは強く強調される:

*single asterisks* は1つのアスタリスクとして表示される。

**double asterisks** はダブルアスタリスクで表示される。

バックスラッシュ・エスケープしてリテラル・アスタリスクを挿入する。\* は * として表示される。

Markdownとは異なる、 アンダースコア (_) はテキストを強調するためにサポートされていない。 はテキストを強調するためにサポートされていない。 識別子を強調する

識別子の強調

文書コメント中の識別子のうち、"関数"パラメータであるもの、または、関連する宣言でスコープ内にある 関数のパラメータであるか、関連する宣言のスコープ内にある名前である。 で強調される。 この強調は、イタリック体、太字、ハイパーリンクなどの形をとる。 どのように強調されるかは、それが何であるか("関数"パラメータ、"型")に依存する、 Dキーワードなどである。 識別子の意図しない強調を防ぐために、識別子の前にアンダースコア(_)を付けることができる。 を付けることができる。アンダースコアは出力から取り除かれる。

文字エンティティ

文字には、文書処理者にとって特別な意味を持つものがある。 を持つ文字がある。 に置き換えるのがよい:

文字とエンティティ
CharacterEntity
<&lt;
>&gt;
&&gt; &gt;;

コードセクションの中や、特殊文字の直後に#や文字が続かない場合は、このようにする必要はない。 特殊文字の直後に#や文字が続かない場合は、このようにする必要はない。

句読点のエスケープ

ASCII の句読点記号をバックスラッシュ\ でエスケープする。 こうすると、バックスラッシュを除いた元の文字が出力される。 以下の文字は、代わりに定義済みマクロを出力する:

文字とエスケープマクロ
CharacterMacro
(ドル;(LPAREN)
)ドル;(RPAREN)
,ドル;(COMMA)
$ドル

バックスラッシュを出力するには、単純にバックスラッシュを2つ並べて使う:\\. 埋め込みコードやインラインコード内のバックスラッシュは、句読点をエスケープしないので、そのまま出力に含まれる。 そのまま出力に含まれる。句読点以外の もそのまま出力に含まれる。例:"、 C:\dmd2\bin\dmd.exe は、埋め込まれたバックスラッシュをエスケープする必要はない。

ドキュメントなし

以下のコンストラクトにはドキュメントは生成されない、 たとえドキュメント・コメントがあってもである:

マクロ

ドキュメントのコメント・プロセッサには、シンプルなマクロ テキスト・プリプロセッサが含まれている。 $ (NAME) がセクションテキストに現れると、それは対応する マクロの が現れると、対応するNAME マクロの置換テキストに置き換えられる。 に置き換えられる。 マクロは引数を取ることができる:$(NAME argument) .

例: 
/**
Macros:
 PARAM = <u>$1</u>
 MATH_DOCS = <a href="https://dlang.org/phobos/std_math.html">Math Docs</a>
*/
module math;

/**
 * この関数は、 $(PARAM a) と $(PARAM b) の和を返す。
 * $(MATH_DOCS) も参照のこと。
 */
int sum(int a, int b) { return a + b; }

上記は次のような出力を生成する:

<h1>math</h1>
<dl><dt><big><a name="sum"></a>int <u>sum</u>(int <i>a</i>, int <i>b</i>);
</big></dt>
<dd>This function returns the <u>sum</u> of <u><i>a</i></u> and <u><i>b</i></u>.
 See also the <a href="https://dlang.org/phobos/std_math.html">Math Docs</a>.
</dd>
</dl>

置換されたテキストは、さらにマクロがないか再帰的にスキャンされる。 見つかった場合、それらは順番に展開される。 すでに展開されたマクロが、引数なし、または、囲んでいるマクロと同じ引数テキストで再帰的に見つかった場合、そのマクロは置換される。 すでに展開されたマクロが再帰的に遭遇した場合、引数なし、または囲んでいるマクロと同じ引数テキストを持つ場合、それはテキストなしで置き換えられる。 に置き換えられる。

マクロの引数

マクロを呼び出すとき、識別子の最後から')'で終わるテキストはすべて の最後から ')' を閉じるまでのテキストがマクロの引数として渡される。 に引数として渡される。 $0 パラメータを使って参照できる。 置換テキストの$0 。 は、カンマで区切られた各引数のテキストに置き換えられる。

引数テキストにカンマがある場合、これは複数の引数を表す。 マクロ定義の中では、$1 が最初のコンマまでの引数テキストを表し、 が最初のコンマから マクロ定義内では、2 $ は最初のコンマまでの引数テキストを表し、 は最初のコンマから2番目のコンマまでを表す。 まで、$9 。 $+ は、最初のコンマから末尾の ')' までのテキストを表す。

マクロの定義

マクロの定義は以下のソースによる、 からのものである:

  1. 定義済みマクロ。
  2. で指定されたファイルからの定義。 ファイルから定義される。 またはdmd.confのDDOCFILE設定で指定されたファイルからの定義。
  3. コマンドラインで指定された*.ddocファイルからの定義。
  4. Ddocによって生成されたランタイム定義。
  5. Macros: セクションからの定義

マクロの再定義は、同じ名前の以前の定義を置き換える。 つまり、さまざまなソースからの一連のマクロ定義が階層を形成する。 階層を形成する。

D_"と "DDOC_"で始まるマクロ名は予約されている。

定義済みマクロ

多くのマクロがDdocで定義済みであり、Ddocが書式を設定するのに必要な最小限の定義を表している。 Ddocがフォーマットやハイライトを行うのに必要な最小限の定義である。 に必要な最小限の定義を表している。 定義はシンプルなHTMLのためのものである。

すべての定義済みマクロの実装は実装系定義である。参照実装のマクロ定義は 参照実装のマクロ定義はここにある。

DdocはHTMLコードを生成しない。基本的な フォーマット・マクロにフォーマットする。 にフォーマットされ、HTMLに展開される。 HTML以外の出力が必要な場合は、これらのマクロを再定義する必要がある。 を再定義する必要がある。

定義済みの書式設定マクロ
NameDescription
B引数を太字にする
I引数を斜体にする
U引数に下線を引く
P引数が段落である
DL引数が定義リストである
DT引数は定義リスト内の定義である
DD引数は定義の説明である
TABLE引数は表である
TRargumentは表の行である
THargumentは行のヘッダー項目である
TDargumentは行のデータ項目である
OLargumentは順序付きリストである
ULargumentは順序なしリストである。
LIargumentはリスト内の項目である
BIGargumentはフォントサイズが1つ大きい
SMALLargumentはフォントサイズを1つ小さくする
BR改行する
LINK引数でクリッカブルリンクを生成する
LINK2クリッカブルリンクを生成する。
RED引数を赤にする
BLUE引数を青にする
GREEN引数は緑に設定される
YELLOW引数は黄色に設定される
BLACK引数は黒に設定される
WHITE引数は白に設定される
D_CODE引数がDコードである
D_INLINECODE引数がインラインDコードである
LF改行を入れる
LPAREN左括弧を挿入する
RPAREN右括弧を挿入する
BACKTICKバックティックを挿入する
DOLLARドル記号を挿入する
DDOC出力の全体テンプレート
ESCAPES置換する文字

DDOC は、生成されたテキスト全体が挿入される定型文を指定するという点で特殊である。 を指定するという点で特別である。 Ddoc generated macroBODY) に挿入されるボイラープレートを指定するという点で特別である。例": スタイルシートを使用する。 を使うために、DDOC は次のように再定義される: 

DDOC = <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
        "http://www.w3.org/TR/html4/strict.dtd">
    <html><head>
    <META http-equiv="content-type" content="text/html; charset=utf-8">
    <title>$(TITLE)</title>
    <link rel="stylesheet" type="text/css" href="style.css">
    </head><body>
    <h1>$(TITLE)</h1>
    $(BODY)
    </body></html>

ESCAPES は、特殊文字を文字列に置き換える一連の置換を定義する。 文字列で置き換える一連の置換を定義する。これは、出力形式が特定の文字のエスケープを必要とする場合に便利である。 例えば、HTMLでは& はエスケープされる。 &amp; でエスケープする。 構文は/c/string/ である。c は1文字か、空白またはカンマで区切られた複数文字である。 string は置換テキストである。

ESCAPES = /&/AddressOf!/
          /!/Exclamation/
          /?/QuestionMark/
          /,/Comma/
          /{ }/Parens/
          /<,>/Arrows/

Dコードのハイライトは以下のマクロによって行われる:

Dコードの書式設定マクロ
NameDescription
D_COMMENTコメントの強調表示
D_STRING文字列リテラルのハイライト表示
D_KEYWORDDキーワードのハイライト表示
D_PSYMBOL現在の宣言名のハイライト表示
D_PARAM現在の関数宣言パラメーターのハイライト表示

ハイライト・マクロはDDOC_ で始まる。 これらはプレゼンテーションの個々の部分の書式を制御する。

Ddocセクションフォーマットマクロ
NameDescription
DDOC_CONSTRAINTテンプレート制約をハイライトする
DDOC_COMMENT出力にコメントを挿入する。
DDOC_DECL宣言の強調表示
DDOC_DECL_DD宣言の説明の強調表示
DDOC_DITTO同上宣言の強調表示
DDOC_SECTIONSすべてのセクションの強調表示
DDOC_SUMMARY要約セクションのハイライト表示
DDOC_DESCRIPTION説明セクションのハイライト表示。
DDOC_AUTHORS作者セクションのハイライト表示
DDOC_BUGSバグセクションのハイライト表示。
DDOC_COPYRIGHT著作権セクションのハイライト表示。
DDOC_DATE日付セクションのハイライト表示。
DDOC_DEPRECATED非推奨セクションのハイライト表示。
DEPRECATED非推奨宣言のラッパー。
DDOC_EXAMPLES例: セクションのハイライト表示。
DDOC_HISTORY履歴セクションのハイライト表示。
DDOC_LICENSEライセンスセクションのハイライト表示。
DDOC_OVERLOAD_SEPARATOR指定された名前のオーバーロードの間に区切り文字を挿入する。
DDOC_RETURNSreturn セクションのハイライト表示。
DDOC_SEE_ALSOSee-also セクションのハイライト表示。
DDOC_STANDARDSstandardsセクションのハイライト表示
DDOC_THROWSthrowsセクションをハイライト表示する。
DDOC_VERSIONバージョンセクションのハイライト表示
DDOC_SECTION_H非標準セクションのセクション名の強調表示。
DDOC_SECTION非標準セクションの内容のハイライト表示
DDOC_MEMBERSクラスや構造体などのすべてのメンバーのデフォルトのハイライト表示
DDOC_MODULE_MEMBERSモジュールのすべてのメンバのハイライト表示
DDOC_CLASS_MEMBERSクラスのすべてのメンバーのハイライト表示
DDOC_STRUCT_MEMBERS構造体のすべてのメンバーの強調表示
DDOC_ENUM_MEMBERS列挙型のすべてのメンバーのハイライト表示。
DDOC_TEMPLATE_PARAMテンプレートの個々のパラメータの強調表示
DDOC_TEMPLATE_PARAM_LISTテンプレートのパラメータ・リストの強調表示
DDOC_TEMPLATE_MEMBERSテンプレートのすべてのメンバーの強調表示
DDOC_ENUM_BASETYPE列挙型のハイライト表示
DDOC_PARAMS関数パラメータセクションの強調表示。
DDOC_PARAM_ROWname=value 関数パラメータの強調表示。
DDOC_PARAM_IDパラメータ名の強調表示
DDOC_PARAM_DESCパラメータ値の強調表示
DDOC_BLANKLINE空行を挿入する。
DDOC_ANCHOR特定の宣言セクションへのハイパーリンクに使用される名前付きアンカーに展開する。 特定の宣言セクションへのハイパーリンクに使用される名前付きアンカーに展開する。引数 &dollar;1 は、修飾された宣言名に展開される。
DDOC_PSYMBOL特定のセクションが参照している宣言名を強調表示する。
DDOC_PSUPER_SYMBOLクラスの基本型を強調表示する。
DDOC_KEYWORDDキーワードの強調表示
DDOC_PARAM関数パラメータの強調表示。
DDOC_BACKQUOTEDインラインコードの挿入
DDOC_AUTO_PSYMBOL_SUPPRESSアンダースコアで始まる自動検出シンボルの強調表示
DDOC_AUTO_PSYMBOL自動検出されたシンボルのハイライト表示
DDOC_AUTO_KEYWORD自動検出されたキーワードのハイライト表示
DDOC_AUTO_PARAM自動検出されたパラメータのハイライト表示

例えば、DDOC_SUMMARY を再定義することができる: 

DDOC_SUMMARY = $(GREEN $0)

そして、すべての要約セクションが緑色になる。

sc.ini のDDOCFILEからのマクロ定義

マクロ定義のテキストファイルが作成できる、 を作成し、sc.ini で指定する: 

DDOCFILE=myproject.ddoc

コマンドラインで.ddocファイルからマクロを定義する

DMDコマンドライン上の拡張子 .ddocはテキストファイルで、順番に読み込まれて処理される。

Ddocが生成するマクロ定義

生成されたマクロ定義
Macro NameContent
BODY 生成されたドキュメントのテキストに設定する。
TITLE モジュール名に設定する。
DATETIME 現在の日時を設定する。
YEAR 現在の年に設定する。
COPYRIGHT モジュールのコメントの一部であるCopyright: セクションの内容に設定する。 モジュールのコメントの一部である
DOCFILENAME 生成される出力ファイルの名前を設定する。
SRCFILENAME 生成された出力ファイルの名前を設定する。 から生成される。

ユニットテストからサンプルを生成するためにDdocを使用する。

Ddocは宣言の使用例を自動的に生成することができる。 の使用例を自動生成できる。宣言の後に文書化された 宣言の後に、ドキュメント化されたユニットテストが続く場合、そのテストのコードは宣言のサンプルセクションに挿入される。 セクションに挿入される。これにより、よくある これは、コードの一部に対して古いドキュメントが存在するという、よくある問題を回避する。

ドキュメント化されたユニットテストを作成するには、次のようにunittestブロックの前に3つの前方スラッシュ unittestブロックの前にスラッシュを3つ追加する:

///
unittest
{
    ...
}

詳細は 文書化されたユニットテストの項を参照のこと。

他のドキュメントにDdocを使う

Ddocは主に、埋め込まれたコメントからドキュメントを作成するために設計されている。 を作成するために設計されている。しかし 他の一般的なドキュメントの処理にも使える。 その理由は、Ddocのマクロ機能とDコードの構文強調表示を利用するためだ。 Ddocのマクロ機能とDコードの構文ハイライト機能を利用するためだ。 機能を利用することである。

.dソース・ファイルが"Ddoc"という文字列で始まっている場合、それは汎用のドキュメントとして扱われる。 という文字列で始まる場合は、D コードのソースファイルとしてではなく、汎用ドキュメントとして扱われる。文字列 "Ddoc"の直後から の直後からファイルの終わりまで、または "Macros:"セクションがドキュメントを形成する。 ドキュメントを形成する。そのテキストに自動的なハイライトは行われない、 で区切られた行の間に埋め込まれたDコードのハイライト以外には、そのテキストに自動的なハイライトは行われない。 で区切られた行の間に埋め込まれたDコードのハイライト以外には、そのテキストに対して自動的なハイライトは行われない。マクロ処理だけが行われる。

Dドキュメントの多くは、この方法で生成されている、 このページもそうだ。 このようなドキュメントは、一番下に と表示されている。

セキュリティについて

DDocのコメントには、以下のような生のHTMLを埋め込むことができる。 <タグを含む。信頼できないソースから生成された レンダリングされたDDocのHTMLを信頼できないソースから生成されたものを公開したり配布したりするときには注意してください。 クロスサイトスクリプティングを許してしまう可能性があるからだ。

Dドキュメント・ジェネレーターへのリンク

Ddocを使用する現在のDドキュメンテーション・ジェネレーターのリストは を使う現在のDドキュメンテーション・ジェネレーターの一覧はwikiページにある。