{首页主词},&

Ddoc文檔注釋學習筆記

2010-01-13 22:52:58 作者: 來源:

Ddoc學習筆記

ddoc的英文文檔在：
http://www.digitalmars.com/d/ddoc.html

D語言可以在代碼中嵌入文檔注釋（以下稱文檔）。
它不僅僅是注釋，而且還是一段可供閱讀的文檔。
這樣做的好處是，在開發(fā)、維護代碼的時候，就能同時維護文檔。
對于程序員，寫文檔比寫代碼還痛苦；寫注釋倒是一個大家還可以接受的事情。
在寫代碼的時候，順便把文檔寫了，也許能改善一下文檔不全的問題。
個人挺喜歡這樣方式的。至于太團隊項目開發(fā)中有沒有效果。
因為還沒有實踐過，不敢亂做評判。

文檔有以下幾個步驟處理:

詞法文檔注釋被附加的記號標識..
解析文檔注釋被關聯到特殊的定義和組合
段落每個文檔注釋被分解到一個段落的序列
處理特定的節(jié).
非特殊的段落完成后高亮顯示.
合并模塊中的所有段落.
在最終結果執(zhí)行宏文本替換.

下面按照這個順序來展開；

推薦先熟悉文檔的寫法，一般編譯方法，常用節(jié)；和學習使用Candydoc；
其他內容可以后期在看；

文檔的語法

從一個最簡單的程序開始吧：

Java代碼

/**
* 這個一個Ddoc文檔例子
*
* Authors: Dehong Liu
* Date: 2007年8月13日
*/
void main()
{
}

/**
 * 這個一個Ddoc文檔例子
 * 
 * Authors: Dehong Liu
 * Date:    2007年8月13日
 */

void main()
{
}

注意注釋符號 /**，和單詞Authors/Date。

編譯這個文件(a1.d)，并且生成文檔doc1/a1.html

Java代碼

dmd -Dddoc1 a1.d # -DdXXX 指定文檔生成路徑為XXX

dmd -Dddoc1 a1.d			# -DdXXX 指定文檔生成路徑為XXX

用瀏覽器打開這個html文件，看起來像下面這樣【見附件 doc1/a1.html】：

Java代碼

a1
void main();
這個一個Ddoc文檔例子
Authors:
Dehong Liu
Date:
2007年8月13日
-------------------------------------------------------------
Page generated by Ddoc.

a1

void main();
    這個一個Ddoc文檔例子

    Authors:
    Dehong Liu

    Date:
    2007年8月13日 

-------------------------------------------------------------	
Page generated by Ddoc.

看著很奇怪？這只是個開始。至少明白了哪些寫法會變成文檔，表現形式和怎么生成。

現在一個個開始解釋。
文檔有下面三種寫法：

Java代碼

/** ... */ / 后面兩個*
/++ ... +/ / 后面兩個+
/// 三個 /

 
 /** ...   */       	/ 后面兩個*	
 /++ ...   +/       	/ 后面兩個+
 ///					三個 /

下面有一個完整的文檔寫法例子（a2.d）：

Java代碼

/// 這是一個行文檔注釋
/** 這也是 */
/++ 同樣 +/
/**
這是一個摘要文檔
*/
/**
* 開頭的* 不是文檔的一部分
*/
/*********************************
在 /** 后面的連續(xù)的*，
不是文檔的一部分
*/
/++
這也是一個摘要文檔
+/
/++
+ 開頭的+ 不是文檔的一部分
+/
/+++++++++++++++++++++++++++++++++
在／++ 后面的連續(xù)的+，
不是文檔的一部分
上面的斜杠是中文符號，避免語法錯誤
換行：注意上面的空行
+/
/*********** 前面連續(xù)的*號不是，這部分*****是文檔，后面的又不是 *****************/
module a2;

/// 這是一個行文檔注釋

/** 這也是 */

/++ 同樣 +/

/**
   這是一個摘要文檔
 */

/**
 * 開頭的* 不是文檔的一部分
 */

/*********************************
   在 /** 后面的連續(xù)的*，
   不是文檔的一部分
 */

/++
   這也是一個摘要文檔
 +/

/++
 + 開頭的+ 不是文檔的一部分
 +/

/+++++++++++++++++++++++++++++++++
   在 ／++ 后面的連續(xù)的+，
   不是文檔的一部分
   上面的斜杠是中文符號，避免語法錯誤

   換行：注意上面的空行
 +/

/*********** 前面連續(xù)的*號不是，這部分*****是文檔，后面的又不是  *****************/

module a2;

輸出的html結果【見附件 doc1/a2.html】：

Java代碼

a2
這是一個行文檔注釋
這也是
同樣
這是一個摘要文檔
開頭的* 不是文檔的一部分
在 /** 后面的連續(xù)的*，不是文檔的一部分
這也是一個摘要文檔
開頭的+ 不是文檔的一部分
在／++ 后面的連續(xù)的+，不是文檔的一部分上面的斜杠是中文符號，避免語法錯誤
換行：注意上面的空行
前面連續(xù)的*號不是，這部分*****是文檔，后面的又不是

a2
這是一個行文檔注釋

這也是

同樣



這是一個摘要文檔



開頭的* 不是文檔的一部分



在 /** 后面的連續(xù)的*， 不是文檔的一部分



這也是一個摘要文檔



開頭的+ 不是文檔的一部分



在 ／++ 后面的連續(xù)的+， 不是文檔的一部分 上面的斜杠是中文符號，避免語法錯誤

換行：注意上面的空行

前面連續(xù)的*號不是，這部分*****是文檔，后面的又不是

文檔和申明關聯

每一個文檔都和一個申明(declaration)相關聯：

引用

1. 如果某單行文檔的最左邊是空格，它就和下面的申明關聯
2. 多個關聯到同一個申明的文檔會被連接在一起
3. 沒有關聯到申明的文檔會被忽略
4. 在module申明前的所有文檔會被應用到整個模塊
5. 如果文檔出現在申明的右邊，則關聯到它
6. 如果文檔只是ditto，則應用上一個申明的文檔
7. 如果一個申明沒有文檔，則不會出現在html輸出中，要出現，可以寫一個空的文檔，如 ///

看一個例子吧：

Java代碼

/**
* 整個模塊的文檔
*/
module a3;
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
{
}
int h; // 只有注釋，沒有文檔，不會出現在html中
// 下面是空文檔
int j; ///
/// 被忽略的文檔

/**
 * 整個模塊的文檔
 */

module a3;

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
{
}

int h; // 只有注釋，沒有文檔，不會出現在html中

// 下面是空文檔
int j; /// 

/// 被忽略的文檔

看起來像這樣【見附件 doc1/a3.html】

Java代碼

a3
整個模塊的文檔
int a;
a;的文檔，b沒有文檔
int c;
int d;
c和d的文檔
再添加些c和d的文檔的文檔
int e;
int f;
e和f的文檔
int g;
g的文檔
在添加點g的文檔
class C;
class D;
C和D的文檔
int x;
C.x的文檔
int y;
int z;
C.y 和 C.z的文檔
int j;

a3
整個模塊的文檔

int a;
    a;的文檔，b沒有文檔

int c;
int d;
    c和d的文檔

    再添加些c和d的文檔的文檔

int e;
int f;
    e和f的文檔

int g;
    g的文檔

    在添加點g的文檔

class C;
class D;
    C和D的文檔

    int x;
        C.x的文檔

    int y;
    int z;
        C.y 和 C.z的文檔

int j;

文檔的節(jié)

a1.d例子中的Authors / Date 就是節(jié)(Sections)。
節(jié)由 "非空格字符" + ":" 組成，其中標識符部分叫節(jié)名，它不區(qū)分大小寫

概要(Summary)：
第一個節(jié)就是概要，它沒有節(jié)名；
它是第一個段落，遇到空行或者節(jié)名結束；
可以把概要寫成多行,但寫成一行比較好
概要節(jié)是可選的

描述(Description)：
第二個沒有名字的節(jié) 是描述
遇到一個節(jié)名或者到文檔的結束

給個例子(a4.d)：

Java代碼

/***********************************
* 這是一個概要(Brief summary)
* 描述myfunch函數的使用；這兩行形成一個概要節(jié)
*
* 描述節(jié)的第一個段落
*
* 還是描述節(jié)：
* 可以寫更多內容
*/
void myfunc() { }

/***********************************
 * 這是一個概要(Brief summary)
 * 描述myfunch函數的使用；這兩行形成一個概要節(jié)
 *
 * 描述節(jié)的第一個段落
 *
 * 還是描述節(jié)：
 * 可以寫更多內容
 */

void myfunc() { }

html輸出【見附件 doc1/a4.html】：

Java代碼

void myfunc();
這是一個概要(Brief summary) 描述myfunch函數的使用；這兩行形成一個概要節(jié)
描述節(jié)的第一個段落
還是描述節(jié)：可以寫更多內容

void myfunc();
    這是一個概要(Brief summary) 描述myfunch函數的使用；這兩行形成一個概要節(jié)

    描述節(jié)的第一個段落

    還是描述節(jié)： 可以寫更多內容

標準節(jié)

有一些預定義好了的節(jié)，看看它們的意思：

Authors: 列出作者名字
Bugs: 列出已知BUG
Date: 列出當前修訂的時間，應當是 std.date 能解析的形式
Deprecated: 做 "抗議"標記(？棄用標記)--最好給出理由和糾正的方法
Examples: 例子
History: 修訂歷史
License: 版權申明
Returns: 解釋函數的返回值；如果返回void，就不要寫在文檔中了
See_Also: 列出相關符號，或者URL鏈接
Standards: 如果申明涉及到某個標準，在此描述
Throws: 列出在哪些環(huán)境下會拋出異常
Version: 指定當前申明的版本號
See_Also: 列出相關符號，或者鏈接
See_Also: 列出相關符號，或者鏈接

特殊節(jié)：一些有特殊含義和語法的節(jié)

Copyright: 版權申明。如果是在module申明中，該節(jié)會被COPYRIGHT宏替換；
Params: 函數的參數描述文檔； "標識符 =' 開始一個新的參數描述；它可以跨越多行
Macros: 和Params節(jié)有類似的語法；它是一系列 NAME=value 組成 NAME 是宏名，VALUE是要替換成的文字

全部列出來看看：

Java代碼

/** Copyright: Public Domain */
module a5;
/**
* Authors: Melvin D. Nerd, melvin@mailinator.com
*
* Bugs: Doesn't work for negative values.
*
* Date: March 14, 2003
*/
void foo1() {}
/**
* Deprecated: superseded by function bar().
*/
deprecated void foo2() { }
/**
* Examples:
* --------------------
* writefln("3"); // writes '3' to stdout
* --------------------
*
* History:
* V1 is initial version
*
* V2 added feature X
*
* License: use freely for any purpose
*/
void bar() { }
/**
* Read the file.
* Returns: The contents of the file.
*/
void[] readFile(char[] filename) { return "filename"; }
/**
* See_Also:
* foo, bar, http://www.digitalmars.com/d/phobos/index.html
*
* Standards: Conforms to DSPEC-1234
*
* Throws: WriteException on failure.
*
* Version: 1.6a
*/
void writeFile(char[] filename) { }
// 特殊節(jié)
/***********************************
* foo does this.
* Params:
* x = is for this
* and not for that
* y = is for that
*/
void foo(int x, int y)
{
}
/**
* Macros:
* FOO = now is the time for
* all good men
* BAR = bar
* MAGENTA = <font color=magenta></font>
* COPYRIGHT = 版權歸熱愛地球的火星人所有
*/
/**
* Foo: $(FOO)
* Bar: $(BAR)
* MAGENTA: $(MAGENTA)
* Copyright: Public Domain
*/
void foo3() { }

/** Copyright: Public Domain */

module a5;

/**
 * Authors: Melvin D. Nerd, melvin@mailinator.com
 *
 * Bugs: Doesn't work for negative values.
 *
 * Date: March 14, 2003
 */

void foo1() {}

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

deprecated void foo2() {  }

/**
 * Examples:
 * --------------------
 * writefln("3"); // writes '3' to stdout
 * --------------------
 *
 * History:
 *  V1 is initial version
 *
 *  V2 added feature X
 *
 * License: use freely for any purpose
 */

void bar() { }

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

void[] readFile(char[] filename) { return "filename"; }

/**
 * See_Also:
 *    foo, bar, http://www.digitalmars.com/d/phobos/index.html
 *
 * Standards: Conforms to DSPEC-1234
 *
 * Throws: WriteException on failure.
 *
 * Version: 1.6a
 */

void writeFile(char[] filename) {  }

// 特殊節(jié)

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

void foo(int x, int y)
{
}

/**
 * Macros:
 *  FOO =   now is the time for
 *      all good men
 *  BAR =   bar
 *  MAGENTA =   <font color=magenta></font>
 *  COPYRIGHT = 版權歸熱愛地球的火星人所有
 */

/**
 * Foo: $(FOO)
 * Bar: $(BAR)
 * MAGENTA: $(MAGENTA)
 * Copyright: Public Domain 
 */
void foo3() {   }

輸出效果是【見附件doc1/a5.html】：

Java代碼

a5
void foo1();
Authors:
Melvin D. Nerd, melvin@mailinator.com
BUGS:
Doesn't work for negative values.
Date:
March 14, 2003
deprecated void foo2();
Deprecated:
superseded by function bar().
void bar();
Examples:
writefln("3"); // writes '3' to stdout
History:
V1 is initial version
V2 added feature X
License:
use freely for any purpose
void[] readFile(char[] filename);
Read the file.
Returns:
The contents of the file.
void writeFile(char[] filename);
See Also:
foo, bar, http://www.digitalmars.com/d/phobos/index.html
Standards:
Conforms to DSPEC-1234
Throws:
WriteException on failure.
Version:
1.6a
void foo(int x, int y);
foo does this.
Params:
int x is for this and not for that
int y is for that
void foo3();
Foo:
now is the time for all good men
Bar:
bar
MAGENTA:
<font color=magenta></font>
Copyright:
Public Domain
Page generated by Ddoc. 版權歸熱愛地球的火星人所有

a5

void foo1();
    Authors:
    Melvin D. Nerd, melvin@mailinator.com

    BUGS:
    Doesn't work for negative values.

    Date:
    March 14, 2003

deprecated void foo2();
    Deprecated:
    superseded by function bar().

void bar();
    Examples:

     writefln("3"); // writes '3' to stdout



    History:
    V1 is initial version

    V2 added feature X

    License:
    use freely for any purpose

void[] readFile(char[] filename);
    Read the file.

    Returns:
    The contents of the file.

void writeFile(char[] filename);
    See Also:
    foo, bar, http://www.digitalmars.com/d/phobos/index.html

    Standards:
    Conforms to DSPEC-1234

    Throws:
    WriteException on failure.

    Version:
    1.6a

void foo(int x, int y);
    foo does this.

    Params:
    int x 	is for this and not for that
    int y 	is for that

void foo3();
    Foo:
    now is the time for all good men

    Bar:
    bar

    MAGENTA:
    <font color=magenta></font>

    Copyright:
    Public Domain

Page generated by Ddoc. 版權歸熱愛地球的火星人所有

上面的例子都還好理解，把不容易理解的說說：
/** Copyright: Public Domain */ 在module申明前和后的效果不一樣；
前者的效果在哪里？看頁面的最后一行

代碼的文檔是這么寫的：

Java代碼

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

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

代碼的上下有一條分割線：至少三個連字符(-)

文檔的高亮處理

內嵌注釋 Embedded Comments
不懂

內嵌代碼 Embedded Code
上面已經演示了

內嵌的HTML Embedded HTML
內嵌的HTML代碼不會被轉譯，直接輸出給html文件
雖然如此，基于某些原因（我沒看懂），還是最好不要用html

Java代碼

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

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

強調 Emphasis
函數參數等標識符會被以斜體，粗體，超鏈接等形式強調處理；具體形式文檔沒有說

特殊符號Character Entities
< > & 有特殊含義，如果要使用這3個符號，換成相應的：< > &
以下情況除外：在代碼節(jié)中；不是立即跟一個 # 或字母

文檔的宏

宏來自于下面這些地方，并按照特定步驟處理：

預定義宏
sc.ini配置文件中的DDOCFILE項指定的文件
命令行指定的*.ddoc文件
Ddoc運行時產生的定義，如BODY,TITLE
文件中的宏節(jié)

宏主要用在對文檔格式的自定義上。
通過修改宏，能自定義HTML輸出格式。

CandyDoc的使用

dmd默認的格式很簡單，可以使用CandyDoc來美化文檔格式和增強功能。
使用方法很簡單：(.ddoc是宏文件的后綴)
下載CandyDoc程序
主頁：http://www.dsource.org/projects/helix/wiki/CandyDoc
下載：http://svn.dsource.org/projects/helix/downloads/candydoc-0.80.zip

假設要編譯: a5.d doc2/candydoc

Java代碼

dmd -c -Dddoc2 a5.d doc2/candydoc/*.ddoc

dmd -c -Dddoc2 a5.d doc2/candydoc/*.ddoc

生成的a5.html文件在 doc2/目錄下，和candydoc一個目錄，如果不是同一目錄，會顯示不正常；

candydoc有2個.ddoc文件：candy.ddoc modules.ddoc
如果要定義樣式，在candy.ddoc中定義，一般不改；
modules.ddoc 要修改成自己的模塊，默認是：

Java代碼

MODULES =
$(MODULE helix.basic)
$(MODULE helix.color)
$(MODULE helix.config)
$(MODULE helix.linalgebra)

MODULES = 
    $(MODULE helix.basic)
    $(MODULE helix.color)
    $(MODULE helix.config)
    $(MODULE helix.linalgebra)

以上面的5個程序為例：

Java代碼

MODULES =
$(MODULE a.a1)
$(MODULE a.a2)
$(MODULE a.a3)
$(MODULE a.a4)
$(MODULE a.a5)

MODULES =
    $(MODULE a.a1)
    $(MODULE a.a2)
    $(MODULE a.a3)
    $(MODULE a.a4)
    $(MODULE a.a5)

編譯之：

Java代碼

dmd -c -Dddoc2 a1 a2 a3 a4 a5.d doc2/candydoc/*.ddoc

dmd -c -Dddoc2 a1 a2 a3 a4 a5.d doc2/candydoc/*.ddoc

如果要用Candydoc替換默認的文檔格式，這么做：
修改dmd.conf文件，添加一行：
DDOCFILE=candy.ddoc
看起來像這樣

Java代碼

[Environment]
DFLAGS=-I%@P%/../src/phobos -L-L%@P%/../lib -L-L/usr/lib -L-L/usr/local/lib -version=Phobos
DDOCFILE=candy.ddoc

[Environment]
DFLAGS=-I%@P%/../src/phobos -L-L%@P%/../lib -L-L/usr/lib -L-L/usr/local/lib -version=Phobos
DDOCFILE=candy.ddoc

上面的配置只寫了candy.ddoc文件，沒有寫module.ddoc。所以編譯的時候要添加module.ddoc，這樣做很不爽；
我的辦法是自己寫一個.ddoc文件--proj.ddoc
把candydoc.ddoc和 module.ddoc兩個文件合并在一起

[模塊部分的導航要求所有的html都在一個目錄下，這點還沒有仔細研究，回頭再寫]

注意，如果沒有效果，檢查：
1. Linux是修改dmd.conf文件；Windows是修改sc.ini文件；不要弄錯了
2. dmd.conf 可能在多個地方：/etc 或 dmd命令所在目錄等
3. candy.doc是相對于當前目錄而已，不是dmd.conf文件；請按照實際情況設定路徑

文檔用起來還算簡單，開始會不習慣，慢慢就習慣了。

安徽新華電腦學校專業(yè)職業(yè)規(guī)劃師為你提供更多幫助【在線咨詢】

上一篇：Build編譯工具學習筆記：常用命令參數和BRF文件 下一篇：Dmd編譯器學習筆記

相關熱詞搜索：注釋文檔筆記