문서 생성기

문서 생성기 (Documentation Generator)

D 프로그래밍 언어는 실제 코드와 함께 계약(contract)과 테스트 코드를 임베드할 수 있게 해 주며, 이것들이 서로 일관성을 유지하도록 도와줘요. 부족한 한 가지는 문서인데, 일반 주석은 자동 추출 및 매뉴얼 페이지로의 포맷팅에 보통 부적합하기 때문이에요. 사용자 문서를 소스 코드에 임베드하는 것은 문서를 두 번 작성하지 않아도 된다는 점, 문서가 코드와 일관성을 유지할 가능성이 높아진다는 점 같은 중요한 이점이 있어요.

출처: Documentation Generator

본문

이에 대한 기존 접근 방식 중 일부는 다음과 같아요.

Doxygen — 이미 D에 대한 일부 지원이 있음
Java의 Javadoc — 아마 가장 잘 알려짐
C#의 임베디드 XML
기타 문서 도구

D의 임베디드 문서 목표는 다음과 같아요.

추출·처리된 후뿐만 아니라 임베디드 문서로도 보기 좋아야 함
쉽고 자연스럽게 작성할 수 있어야 함 — 즉 완성된 문서에서는 볼 수 없는 및 기타 서투른 형식에 대한 의존을 최소화해야 함
컴파일러가 코드 파싱에서 이미 아는 정보를 반복하지 않아야 함
다른 목적을 위한 추출과 포맷팅을 방해하므로 임베디드 HTML에 의존하지 않아야 함
기존 D 주석 형식에 기반하므로, D 코드에만 관심 있는 파서와 완전히 독립적이어야 함
코드와 시각적으로 혼동되지 않도록 코드와 다르게 보이고 느껴져야 함
원하면 사용자가 Doxygen 또는 다른 문서 추출기를 사용할 수 있어야 함

명세 (Specification)

임베디드 문서 주석 형식에 대한 명세는 정보가 컴파일러에 어떻게 제시되는지만 명시해요. 그 정보가 어떻게 사용되고 최종 표현의 형식이 무엇인지는 구현 정의예요. 최종 표현 형식이 HTML 웹 페이지인지, man 페이지인지, PDF 파일인지 등은 D 프로그래밍 언어의 일부로 명시되지 않아요.

처리 단계 (Phases of Processing)

임베디드 문서 주석은 일련의 단계로 처리돼요.

어휘(Lexical) — 문서 주석이 식별되어 토큰에 연결됨
파싱(Parsing) — 문서 주석이 특정 선언과 연관되고 결합됨
섹션(Sections) — 각 문서 주석이 일련의 섹션으로 나뉘어짐
특수 섹션이 처리됨
비특수 섹션의 하이라이팅이 수행됨
모듈의 모든 섹션이 결합됨
매크로 및 이스케이프 텍스트 치환이 수행되어 최종 결과를 생성함

어휘 (Lexical)

임베디드 문서 주석은 다음 형식 중 하나예요.

/** ... */ — 여는 / 뒤의 두 개의 *
/++ ... +/ — 여는 / 뒤의 두 개의 +
/// — 세 개의 슬래시

다음은 모두 임베디드 문서 주석이에요.

/// This is a one line documentation comment.

/** So is this. */

/++ And this. +/

/**
   This is a brief documentation comment.
 */

/**
 * The leading * on this line is not part of the documentation comment.
 */

/*********************************
   The extra *'s immediately following the /** are not
   part of the documentation comment.
 */

/++
   This is a brief documentation comment.
 +/

/++
 + The leading + on this line is not part of the documentation comment.
 +/

/+++++++++++++++++++++++++++++++++
   The extra +'s immediately following the / ++ are not
   part of the documentation comment.
 +/

/**************** Closing *'s are not part *****************/

주석 열기, 닫기, 왼쪽 여백의 추가 *와 +는 무시되며 임베디드 문서의 일부가 아니에요. 이 형식 중 하나를 따르지 않는 주석은 문서 주석이 아니에요.

파싱 (Parsing)

각 문서 주석은 선언과 연관돼요. 문서 주석이 한 줄에 있거나 왼쪽에 공백만 있으면 다음 선언을 가리켜요. 같은 선언에 적용되는 여러 문서 주석은 연결(concatenated)돼요. 선언과 연관되지 않은 문서 주석은 무시돼요. ModuleDeclaration보다 앞서는 문서 주석은 전체 모듈에 적용돼요. 문서 주석이 선언과 같은 줄의 오른쪽에 나타나면 그것에 적용돼요.

선언에 대한 문서 주석이 식별자 ditto로만 구성되면, 같은 선언 스코프에서 이전 선언에 대한 문서 주석이 이 선언에도 적용돼요.

선언에 대한 문서 주석이 없으면 그 선언은 출력에 나타나지 않을 수 있어요. 출력에 나타나도록 보장하려면 빈 선언 주석을 넣으세요.

int a;  /// documentation for a; b has no documentation
int b;

/** documentation for c and d */
/** more documentation for c and d */
int c;
/** ditto */
int d;

/** documentation for e and f */ int e;
int f;  /// ditto

/** documentation for g */
int g; /// more documentation for g

/// documentation for C and D
class C
{
    int x; /// documentation for C.x

    /** documentation for C.y and C.z */
    int y;
    int z; /// ditto
}

/// ditto
class D { }

섹션 (Sections)

문서 주석은 일련의 Section 들이에요. Section 은 한 줄에서 첫 번째 비공백 문자가 바로 뒤에 ':'가 오는 이름이에요. 이 이름이 섹션 이름을 형성해요. 섹션 이름은 대소문자를 구분하지 않아요.

'http://' 또는 'https://'로 시작하는 섹션 이름은 섹션 이름으로 인식되지 않아요.

요약 (Summary)

첫 번째 섹션은 Summary 이며 섹션 이름을 가지지 않아요. 빈 줄이나 섹션 이름까지의 첫 번째 문단이에요. 요약은 어떤 길이든 될 수 있지만 한 줄로 유지하는 것이 좋아요. Summary 섹션은 선택적이에요.

설명 (Description)

다음 이름 없는 섹션은 Description 이에요. Summary 뒤에 오는 모든 문단으로 구성되며, 섹션 이름을 만나거나 주석이 끝날 때까지 지속돼요.

Description 섹션은 선택적이지만, Summary 섹션 없이는 Description 이 있을 수 없어요.

/***********************************
 * Brief summary of what
 * myfunc does, forming the summary section.
 *
 * First paragraph of synopsis description.
 *
 * Second paragraph of
 * synopsis description.
 */

void myfunc() { }

명명된 섹션은 Summary 와 Description 이름 없는 섹션 뒤에 온다.

표준 섹션 (Standard Sections)

일관성과 예측 가능성을 위해 여러 표준 섹션이 있어요. 이 중 어느 것도 존재할 필요는 없어요.

Authors: 선언의 저자(들)를 나열해요.

/**
 * Authors: Melvin D. Nerd, [[email protected]](/cdn-cgi/l/email-protection)
 */

Bugs: 알려진 버그를 나열해요.

/**
 * Bugs: Doesn't work for negative values.
 */

Date: 현재 개정판의 날짜를 지정해요. 날짜는 std.date가 파싱할 수 있는 형식이어야 해요.

/**
 * Date: March 14, 2003
 */

Deprecated: 연관된 선언이 deprecated로 표시된 경우 그에 대한 설명과 시정 조치를 제공해요.

/**
 * Deprecated: superseded by function bar().
 */

deprecated void foo() { ... }

Examples: 사용 예시들

/**
 * Examples:
 * --------------------
 * writeln("3"); // writes '3' to stdout
 * --------------------
 */

History: 개정 이력

/**
 * History:
 *      V1 is initial version
 *
 *      V2 added feature X
 */

License: 저작권이 있는 코드에 대한 라이선스 정보

/**
 * License: use freely for any purpose
 */

void bar() { ... }

Returns: 함수의 반환 값을 설명해요. 함수가 void 를 반환하면 중복해서 문서화하지 마세요.

/**
 * Read the file.
 * Returns: The contents of the file.
 */

void[] readFile(const(char)[] filename) { ... }

See_Also: 관련 항목에 대한 다른 심볼과 URL 목록

/**
 * See_Also:
 *    foo, bar, http://www.digitalmars.com/d/phobos/index.html
 */

Standards: 이 선언이 특정 표준을 준수한다면 그 설명이 여기에 들어가요.

/**
 * Standards: Conforms to DSPEC-1234
 */

Throws: 던져지는 예외와 어떤 상황에서 던져지는지를 나열해요.

/**
 * Write the file.
 * Throws: WriteException on failure.
 */

void writeFile(string filename) { ... }

Version: 선언의 현재 버전을 지정해요.

/**
 * Version: 1.6a
 */

특수 섹션 (Special Sections)

일부 섹션은 특별한 의미와 문법을 가져요.

Copyright: 저작권 표기를 담고 있어요. 모듈 선언을 문서화할 때 COPYRIGHT 매크로가 이 섹션의 내용으로 설정돼요. 저작권 섹션은 모듈 선언에 대한 것일 때만 이 특별한 취급을 받아요.

/** Copyright: Public Domain */

module foo;

Params: 함수 매개변수는 params 섹션에 나열함으로써 문서화할 수 있어요. '='가 뒤따르는 식별자로 시작하는 각 줄은 새 매개변수 설명을 시작해요. 설명은 여러 줄에 걸칠 수 있어요.

/***********************************
 * foo does this.
 * Params:
 *      x =     is for this
 *              and not for that
 *      y =     is for that
 */

void foo(int x, int y)
{
}

Macros: 매크로 섹션은 Params: 섹션과 같은 문법을 따라요. NAME=value 쌍의 연속이에요. NAME 은 매크로 이름이고, value 는 대체 텍스트예요.

/**
 * Macros:
 *      FOO =   now is the time for
 *              all good men
 *      BAR =   bar
 *      MAGENTA =   <font color="magenta">$0</font>
 */

하이라이팅 (Highlighting)

임베디드 주석 (Embedded Comments)

문서 주석 자체는 $(DDOC_COMMENT comment text) 문법을 사용해 주석 처리할 수 있어요. 이 주석은 중첩되지 않아요.

임베디드 코드 (Embedded Code)

D 코드는 (공백을 무시하고) 세 개 이상의 하이픈 -, 백틱 ` 또는 물결표 ~로 시작하는 줄을 사용해 코드 섹션을 구분해 임베드할 수 있어요.

/++
 + Our function.
 +
 + Example:
 + ---
 + import std.stdio;
 +
 + void foo()
 + {
 +     writeln("foo!");  /* print the string */
 + }
 + ---
 +/

위 예제에서 문서 주석이 /++ ... +/ 형식을 사용하므로 /* ... */ 를 코드 섹션 안에서 사용할 수 있다는 점에 주의하세요.

D 코드는 자동 구문 하이라이팅을 받아요. 하이라이팅 없이 다른 언어의 코드를 포함하려면 맨 위 구분선 끝에 언어 문자열을 추가하세요.

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

인라인 코드 (Inline Code)

인라인 코드는 GitHub, Reddit, Stack Overflow 및 기타 웹사이트에서 사용되는 문법과 유사하게 백틱 문자() 사이에 작성할 수 있어요. 이 동작을 트리거하려면 여는 와 닫는 ` 가 모두 같은 줄에 나타나야 해요. 백틱 안에서도 매크로는 여전히 확장된다는 점에 주의하세요. 이스케이프도 참고하세요.

이 섹션 안의 텍스트는 위에서 설명한 규칙에 따라 이스케이프된 다음 $(DDOC_BACKQUOTED) 매크로로 감싸져요. 기본적으로 이 매크로는 코드로 포맷된 인라인 텍스트 스팬으로 표시되도록 확장돼요.

리터럴 백틱 문자는 한 줄에서 짝이 없는 ` 로 또는 $(BACKTICK) 매크로를 사용해 출력할 수 있어요.

/// Returns `true` if `a == b`.
void foo() {}

/// Backquoted `<html>` will be displayed to the user instead
/// of passed through as embedded HTML (see below).
void bar() {}

임베디드 HTML (Embedded HTML)

HTML은 문서 주석에 임베드될 수 있으며, HTML 출력으로 변경 없이 전달돼요. 그러나 HTML이 반드시 임베디드 문서 주석 추출기의 원하는 출력 형식일 필요는 없으므로, 실용적인 곳에서는 사용을 피하는 것이 좋아요.

/**
 * Example of embedded HTML:
 *
 * <ol>
 *   <li><a href="http://www.digitalmars.com">Digital Mars</a></li>
 *   <li><a href="http://www.classicempire.com">Empire</a></li>
 * </ol>
 */

제목 (Headings)

긴 문서 섹션은 제목을 추가해 세분화할 수 있어요. 제목은 하나에서 여섯 개의 # 문자로 시작하고 공백과 제목 텍스트가 뒤따르는 텍스트 줄이에요. # 문자 수가 제목 수준을 결정해요. 제목은 선택적으로 끝에 임의 개수의 후행 # 문자로 끝날 수 있어요.

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

링크 (Links)

문서는 다른 문서나 URL에 링크할 수 있어요. 네 가지 링크 스타일이 있어요.

/**
 * Some links:
 *
 * 1. A [reference link][ref] and bare reference links: [ref] or [Object]
 * 2. An [inline link](https://dlang.org)
 * 3. A bare URL: https://dlang.org
 * 4. An ![image](https://dlang.org/images/d3.png)
 *
 * [ref]: https://dlang.org "The D Language Website"
 */

참조 링크 (Reference Links)

참조 스타일 링크는 참조 라벨을 대괄호로 감싸요. 선택적으로 어떤 링크 텍스트가 앞에 올 수 있으며, 그것도 대괄호로 감싼다.

참조 라벨은 다른 곳에서 정의된 참조와 일치해야 해요. 이것은 문서화되는 소스 코드의 스코프에 있는 D 심볼(위 예제의 [Object]처럼)일 수도 있고, 같은 문서 주석에서 정의된 명시적 참조(위 예제의 [ref]처럼)일 수도 있어요. 예제에서 항목 1의 [ref] 인스턴스 두 개 모두 예제 맨 아래의 일치하는 정의의 URL과 제목 텍스트로 대체돼요. 첫 번째 링크는 reference link로, 두 번째는 ref로 읽힐 거예요.

참조 정의는 대괄호 안의 라벨로 시작하고, 콜론, URL, 작은따옴표나 큰따옴표 또는 괄호로 감싼 선택적 제목이 뒤따라요. 참조 라벨이 D 심볼과 참조 정의 모두와 일치하면 참조 정의가 사용돼요.

D 심볼에 대한 생성된 링크는 문서화되는 모듈과 같은 루트 패키지를 가지면 상대적이에요. 그렇지 않으면 URL 앞에 $(DDOC_ROOT_pkg) 매크로가 붙는데, 여기서 pkg는 링크되는 심볼의 루트 패키지예요. D 심볼에 대한 링크는 모듈 이름 뒤에 $(DOC_EXTENSION) 매크로로 생성돼요. 그러면 위 예제의 [Object]에 대한 생성 URL은 다음과 같이 작성된 것과 같아요.

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

DOC_ROOT_ 매크로는 Macros 섹션을 사용해 링크할 외부 패키지에 대해 정의할 수 있어요.

인라인 링크 (Inline Links)

인라인 스타일 링크는 링크 텍스트를 대괄호로, 링크 URL을 괄호로 감싸요. 참조 링크처럼 URL 뒤에는 선택적으로 작은따옴표나 큰따옴표 또는 괄호로 감싼 제목 텍스트가 올 수 있어요.

/// [a link with title text](https://dlang.org 'Some title text')

순수 URL (Bare URLs)

순수 URL은 http:// 또는 https://로 시작하고, 문자·숫자·-_?=%&/+#~., 집합에서 하나 이상의 문자로 계속되며, 최소한 하나의 마침표를 포함하는 문자 시퀀스예요. URL 인식은 모든 매크로 텍스트 치환 전에 발생해요. URL은 $(DDOC_LINK_AUTODETECT) 매크로로 감싸지고 그 외에는 그대로 남아요.

이미지 (Images)

이미지는 참조 또는 인라인 링크와 같은 형식이지만, 초기 대괄호 앞에 느낌표 ! 를 추가해요. 일반 링크에서 링크 텍스트였던 것이 이미지의 alt 텍스트로 사용돼요.

목록 (Lists)

문서에는 목록이 포함될 수 있어요. 숫자와 마침표로 순서 있는 목록을 시작하세요.

/**
 * 1. First this
 * 2. Then this
 *    1. A sub-item
 */

하이픈(-), 별표(*), 플러스(+)로 순서 없는 목록을 시작하세요. 같은 목록의 후속 항목도 같은 기호로 시작해야 해요.

/**
 * - A list
 * - With a second item
 *
 * + A different list
 *   - With a sub-item
 *
 * * A third list (note the double asterisks)
 */

위 예제의 이중 별표에 주의하세요. 목록이 별표로 구분된 문서 주석 안에 있으므로, 초기 별표는 목록 항목이 아니라 문서 주석의 일부로 간주되기 때문이에요. 다른 줄이 별표로 시작하지 않아도 마찬가지예요.

/**
 - A list
 * Not a list because the asterisk is part of the documentation comment
 */

/++
 + + The caveat also applies to plus-delimited documentation comments
 +/

목록 항목은 새 문단, 제목, 임베디드 코드, 자식 목록 항목 같은 내용을 포함할 수 있어요. 내용을 목록 기호 뒤 텍스트의 들여쓰기와 일치하도록 들여쓰기만 하면 돼요.

/**
 * - A parent list item
 *
 *   With a second paragraph
 *
 *   - A sub-item
 *     ---
 *     // A code example inside the sub-item
 *     ---
 */

표 (Tables)

데이터는 표에 넣을 수 있어요. 표는 단일 헤더 행, 구분 행, 0개 이상의 데이터 행으로 구성돼요. 각 행의 셀은 파이프(|) 문자로 구분돼요. 시작과 끝의 | 는 선택적이에요. 구분 행의 셀 수는 헤더 행의 셀 수와 일치해야 해요.

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

구분 행의 셀은 하이픈(-)과 선택적 콜론(:)을 포함해요. 하이픈 왼쪽의 :는 왼쪽 정렬 열을, 하이픈 오른쪽의 :는 오른쪽 정렬 열(위 예제처럼)을, 하이픈 양쪽의 : 는 가운데 정렬 열을 만들어요.

인용 (Quotes)

문서는 섹션의 각 줄에 > 를 접두사로 붙여 인용 자료 섹션을 포함할 수 있어요. 인용은 제목, 목록, 임베디드 코드 등을 포함할 수 있어요.

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

인용 줄 바로 뒤에 오는 텍스트 줄은 인용의 일부로 간주돼요.

/**
 * > This line
 * and this line are both part of the quote
 *
 * This line is not part of the quote.
 */

수평선 (Horizontal Rules)

세 개 이상의 별표, 밑줄 또는 하이픈을 포함하는 줄을 추가해 수평선을 만들어요.

/**
 * ***
 * ___
 */

목록처럼 위 예제의 초기 * 는 별표로 구분된 문서 주석의 일부이므로 제거된다는 점에 주의하세요. 최소한 세 개의 후속 별표가 필요해요.

하이픈으로 수평선을 만들려면 하이픈 사이에 공백을 추가하세요. 공백이 없으면 임베디드 코드 블록의 시작이나 끝으로 취급돼요. 어떤 수평선이든 공백을 포함할 수 있다는 점에 주의하세요.

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

텍스트 강조 (Text Emphasis)

별표(*)로 감싼 텍스트 스팬은 강조되고, 두 별표(**)로 감싼 텍스트는 강하게 강조돼요.

single asterisks 는 single asterisks 로 렌더링돼요.

double asterisks 는 double asterisks 로 렌더링돼요.

리터럴 별표를 삽입하려면 백슬래시 이스케이프로 처리하세요: * 는 * 로 렌더링돼요.

Markdown과 달리 텍스트 강조에는 밑줄(_)이 지원되지 않아요. snake_case 이름과 식별자 강조의 밑줄 접두사 처리를 깨뜨리기 때문이에요.

식별자 강조 (Identifier Emphasis)

함수 매개변수이거나 연관된 선언의 스코프에 있는 이름인 문서 주석의 식별자는 출력에서 강조돼요. 이 강조는 이탤릭, 볼드, 하이퍼링크 등의 형태를 취할 수 있어요. 어떻게 강조되는지는 그것이 함수 매개변수, 타입, D 키워드인지 등 무엇인지에 달려 있어요. 식별자의 의도하지 않은 강조를 막으려면 밑줄(_)을 앞에 붙일 수 있어요. 밑줄은 출력에서 제거돼요.

동작 플래그 (Behavior Flags)

함수는 프로젝트 README에서 볼 수 있는 빌드 상태 배지와 유사하게, 선언 아래에 표시되는 배지와 같은 동작 플래그 로 동작 보장을 광고할 수 있어요. 어떤 것이 있으면 배지는 Current Behaviors: 라벨로 소개돼요. 네 가지 플래그가 있어요: $(NOALLOC) (No Allocations 로 렌더링), $(NOGC) (No GC 로 렌더링), $(NOTHROW) (No Exceptions Thrown 으로 렌더링), $(PURE) (Is Pure 로 렌더링). 각 플래그는 해당하는 경우에만 표시되며, 각각 구별되는 색으로 렌더링돼요.

$(NOGC), $(NOTHROW), $(PURE) 플래그는 문서화된 선언에 해당 @nogc, nothrow 또는 pure 속성이 있을 때 자동으로 방출돼요. $(NOALLOC) 플래그는 대응하는 언어 속성이 없으며 수동으로 작성할 때만 표시돼요.

어떤 플래그든 문서 주석 어디에나 수동으로 작성할 수도 있어요. 수동으로 작성된 플래그는 선언 제목 아래에 나타나도록 이동되며, 중복 플래그 — 수동으로 작성되었든 속성에서 자동으로 추가되었든 — 는 단일 배지로 통합돼요.

/++
Copy `n` bytes.

$(DOLLAR)(NOALLOC)
+/
void* fastCopy(void* dst, const(void)* src, size_t n) @nogc nothrow pure;

위 예제는 No Allocations 배지(수동 작성)를 No GC, No Exceptions Thrown, Is Pure 배지(속성에서 자동 추가) 옆에 렌더링하며, 모두 함수 제목 아래 Current Behaviors: 라벨 뒤에 표시돼요.

문자 엔티티 (Character Entities)

일부 문자는 문서 처리기에 특별한 의미를 가지므로, 혼동을 피하기 위해 해당 문자 엔티티로 대체하는 것이 좋을 수 있어요.

문자와 엔티티

| 문자 | 엔티티 | | < | < | | > | > | | & | & |

코드 섹션 안이나 특수 문자가 # 또는 문자 바로 뒤에 오지 않으면 이렇게 할 필요가 없어요.

구두점 이스케이프 (Punctuation Escapes)

백슬래시 \ 로 ASCII 구두점 기호를 이스케이프하세요. 그러면 백슬래시 없이 원래 문자를 출력하지만, 다음 문자는 대신 미리 정의된 매크로를 출력해요.

문자와 이스케이프 매크로

| 문자 | 매크로 | | ( | $(LPAREN) | | ) | $(RPAREN) | | , | $(COMMA) | | $ | $(DOLLAR) |

백슬래시를 출력하려면 백슬래시 두 개를 연속으로 사용하면 돼요: \.

임베디드 또는 인라인 코드 안의 백슬래시는 구두점을 이스케이프하지 않고 그대로 출력에 포함된다는 점에 주의하세요. 구두점이 아닌 것 앞의 백슬래시도 그대로 출력에 포함돼요. 예를 들어 C:\dmd2\bin\dmd.exe 는 임베디드 백슬래시를 이스케이프할 필요가 없어요.

문서 없음 (No Documentation)

다음 구성에는 문서 주석이 있어도 문서가 생성되지 않아요.

불변 조건 (Invariants)
Postblits
소멸자 (Destructors)
static 생성자와 static 소멸자
클래스 정보, 타입 정보, 모듈 정보

매크로 (Macros)

문서 주석 처리기는 간단한 매크로 텍스트 전처리기를 포함해요. 섹션 텍스트에 $(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;

/**
 * This function returns the sum of $(PARAM a) and $(PARAM b).
 * See also the $(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>

대체 텍스트는 더 많은 매크로를 위해 재귀적으로 스캔돼요. 발견되면 차례로 확장돼요. 이미 확장된 매크로가 인자 없이 또는 둘러싼 매크로와 같은 인자 텍스트로 재귀적으로 만나면 텍스트 없이 대체돼요.

대체 텍스트 경계를 가로지르는 매크로 호출은 확장되지 않아요.
매크로 이름이 정의되지 않으면 대체 텍스트는 $(DDOC_UNDEFINED_MACRO(NAME)) 이 돼요. 이는 기본적으로 비어 있어요.
$(NAME) 이 매크로 확장 없이 출력에 존재해야 한다면, $ 를 백슬래시 이스케이프할 수 있어요: $.

매크로 인자 (Macro Arguments)

매크로를 호출할 때 식별자 끝에서 닫는 ')'까지의 모든 텍스트가 매크로에 인자로 전달되며, 매크로 정의 안에서 $0 매개변수로 참조할 수 있어요. 대체 텍스트의 $0 는 각 인자의 텍스트로 대체되며, 쉼표로 구분돼요.

인자 텍스트에 쉼표가 있으면 여러 인자를 나타내요. 매크로 정의 안에서 $1 은 첫 번째 쉼표까지의 인자 텍스트를, $2 는 첫 번째 쉼표에서 두 번째 쉼표까지를 나타내며, $9 까지 이어져요. $+ 는 첫 번째 쉼표에서 닫는 ')'까지의 텍스트를 나타내요.

인자 텍스트는 중첩 괄호, "" 또는 '' 문자열, 주석 또는 태그를 포함할 수 있어요.
벗어난, 중첩되지 않은 괄호가 사용되면 백슬래시 이스케이프할 수 있어요: ( 또는 ).
인자 구분자로 의도되지 않은 리터럴 쉼표는 별도의 인자를 기대하는 매크로를 호출할 때 이스케이프할 수 있어요. ARGS=$0 매크로를 정의하면 쉼표를 처리하는 데 유용할 수 있어요 — 다음은 동일해요.
- $(FOO one, $(ARGS two, dwa, dos), three)
- $(FOO one, two, dwa, dos, three).

매크로 정의 (Macro Definitions)

매크로 정의는 지정된 순서로 다음 소스에서 나와요.

미리 정의된 매크로
sc.ini 또는 dmd.conf의 DDOCFILE 설정으로 지정된 파일의 정의
명령행에서 지정된 *.ddoc 파일의 정의
Ddoc이 생성하는 런타임 정의
모든 Macros: 섹션의 정의

매크로 재정의는 같은 이름의 이전 정의를 대체해요. 즉 다양한 소스의 매크로 정의 시퀀스가 계층을 형성해요.

"D_" 및 "DDOC_"로 시작하는 매크로 이름은 예약돼 있어요.

미리 정의된 매크로 (Predefined Macros)

많은 매크로가 Ddoc에 미리 정의되어 있으며, Ddoc이 표현을 포맷하고 하이라이팅하는 데 필요한 최소 정의를 나타내요. 정의는 단순한 HTML을 위한 것이에요.

모든 미리 정의된 매크로의 구현은 구현 정의예요. 참조 구현의 매크로 정의는 여기에서 찾을 수 있어요.

Ddoc은 HTML 코드를 생성하지 않아요. 기본 포맷팅 매크로로 포맷하며, 그것들은 (미리 정의된 형태에서) HTML로 확장돼요. HTML 이외의 출력이 필요하면 이 매크로들을 재정의해야 해요.

미리 정의된 포맷팅 매크로

DDOC는 생성된 텍스트 전체가 삽입되는 뼈대(boilerplate)를 지정한다는 점에서 특별해요 (Ddoc 생성 매크로 BODY로 표현). 예를 들어 스타일 시트를 사용하려면 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에서 & 는 & 로 이스케이프돼야 해요. 문법은 /c/string/ 이며, 여기서 c 는 단일 문자이거나 공백 또는 쉼표로 구분된 여러 문자이고, string 은 대체 텍스트예요.

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

D 코드의 하이라이팅은 다음 매크로에 의해 수행돼요.

D 코드 포맷팅 매크로

하이라이팅 매크로는 DDOC_ 로 시작해요. 그것들은 표현의 개별 부분의 포맷팅을 제어해요.

Ddoc 섹션 포맷팅 매크로

예를 들어 DDOC_SUMMARY를 재정의할 수 있어요.

DDOC_SUMMARY = $(GREEN $0)

그러면 모든 요약 섹션이 초록색이 돼요.

sc.ini의 DDOCFILE에서 온 매크로 정의 (Macro Definitions from sc.ini's DDOCFILE)

매크로 정의 텍스트 파일을 만들어 sc.ini에서 지정할 수 있어요.

DDOCFILE=myproject.ddoc

명령행의 .ddoc 파일에서 온 매크로 정의 (Macro Definitions from .ddoc Files on the Command Line)

확장자가 .ddoc 인 DMD 명령행의 파일 이름은 순서대로 읽고 처리되는 텍스트 파일이에요.

Ddoc이 생성하는 매크로 정의 (Macro Definitions Generated by Ddoc)

생성된 매크로 정의

Ddoc을 사용해 유닛 테스트에서 예제 생성하기 (Using Ddoc to generate examples from unit tests)

Ddoc은 유닛 테스트를 사용해 선언에 대한 사용 예제를 자동 생성할 수 있어요. 선언 뒤에 문서화된 유닛 테스트가 있으면 테스트의 코드가 선언의 예제 섹션에 삽입돼요. 이는 코드 조각에 대한 오래된 문서를 갖는 빈번한 문제를 피해 줘요.

문서화된 유닛 테스트를 만들려면 unittest 블록 앞에 슬래시 세 개를 추가하면 돼요. 이렇게:

///
unittest
{
    ...
}

자세한 내용은 문서화된 유닛 테스트에 대한 전체 섹션을 참고하세요.

Ddoc을 다른 문서에 사용하기 (Using Ddoc for other Documentation)

Ddoc은 주로 임베디드 주석에서 문서를 생성하는 데 사용되도록 설계됐어요. 그러나 일반적인 문서를 처리하는 데에도 사용할 수 있어요. 이렇게 하는 이유는 Ddoc의 매크로 기능과 D 코드 구문 하이라이팅 기능을 활용하기 위해서예요.

.d 소스 파일이 "Ddoc" 문자열로 시작하면 D 코드 소스 파일이 아니라 범용 문서로 취급돼요. "Ddoc" 문자열 바로 다음부터 파일 끝 또는 어떤 "Macros:" 섹션까지가 문서를 형성해요. --- 줄로 구분된 줄 사이에 임베드된 D 코드의 하이라이팅 외에는 그 텍스트에 자동 하이라이팅이 수행되지 않아요. 매크로 처리만 수행돼요.

D 문서 자체의 상당 부분이 이렇게 생성되며, 이 페이지도 마찬가지예요. 그러한 문서는 맨 아래에 Ddoc에 의해 생성되었다고 표시돼요.

보안 고려 사항 (Security considerations)

DDoc 주석은