熱門精品專業(yè)ddoc的英文文檔在：
http://www.digitalmars.com/d/ddoc.html
D語言可以在代碼中嵌入文檔注釋（以下稱文檔）。
它不僅僅是注釋，而且還是一段可供閱讀的文檔。
這樣做的好處是，在開發(fā)、維護代碼的時候，就能同時維護文檔。
對于程序員，寫文檔比寫代碼還痛苦；寫注釋倒是一個大家還可以接受的事情。
在寫代碼的時候，順便把文檔寫了，也許能改善一下文檔不全的問題。
個人挺喜歡這樣方式的。至于太團隊項目開發(fā)中有沒有效果。
因為還沒有實踐過，不敢亂做評判。
文檔有以下幾個步驟處理:
- 詞法 文檔注釋被 附加的記號 標識..
- 解析 文檔注釋 被關(guān)聯(lián)到 特殊的定義和組合
- 段落 每個文檔注釋 被 分解到一個段落的序列
- 處理特定的節(jié).
- 非特殊的段落完成后高亮顯示.
- 合并模塊中的所有段落.
- 在最終結(jié)果執(zhí)行宏文本替換.
下面按照這個順序來展開；
推薦先熟悉文檔的寫法，一般編譯方法，常用節(jié)；和學(xué)習(xí)使用Candydoc；
其他內(nèi)容可以后期在看；
文檔的語法
從一個最簡單的程序開始吧：
Java代碼 
- /**
- * 這個一個Ddoc文檔例子
- *
- * Authors: Dehong Liu
- * Date: 2007年8月13日
- */
- void main()
- {
- }
注意注釋符號 /**，和單詞Authors/Date。
編譯這個文件(a1.d)，并且生成文檔doc1/a1.html
Java代碼
- 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.
看著很奇怪？這只是個開始。至少明白了哪些寫法會變成文檔，表現(xiàn)形式和怎么生成。
現(xiàn)在一個個開始解釋。
文檔有下面三種寫法：
Java代碼
- /** ... */ / 后面兩個*
- /++ ... +/ / 后面兩個+
- /// 三個 /
下面有一個完整的文檔寫法例子（a2.d）：
Java代碼
- /// 這是一個行文檔注釋
- /** 這也是 */
- /++ 同樣 +/
- /**
- 這是一個摘要文檔
- */
- /**
- * 開頭的* 不是文檔的一部分
- */
- /*********************************
- 在 /** 后面的連續(xù)的*，
- 不是文檔的一部分
- */
- /++
- 這也是一個摘要文檔
- +/
- /++
- + 開頭的+ 不是文檔的一部分
- +/
- /+++++++++++++++++++++++++++++++++
- 在 ／++ 后面的連續(xù)的+，
- 不是文檔的一部分
- 上面的斜杠是中文符號，避免語法錯誤
- 換行：注意上面的空行
- +/
- /*********** 前面連續(xù)的*號不是，這部分*****是文檔，后面的又不是 *****************/
- module a2;
輸出的html結(jié)果【見附件 doc1/a2.html】：
Java代碼
- a2
- 這是一個行文檔注釋
- 這也是
- 同樣
- 這是一個摘要文檔
- 開頭的* 不是文檔的一部分
- 在 /** 后面的連續(xù)的*， 不是文檔的一部分
- 這也是一個摘要文檔
- 開頭的+ 不是文檔的一部分
- 在 ／++ 后面的連續(xù)的+， 不是文檔的一部分 上面的斜杠是中文符號，避免語法錯誤
- 換行：注意上面的空行
- 前面連續(xù)的*號不是，這部分*****是文檔，后面的又不是
文檔和申明關(guān)聯(lián)
每一個文檔都和一個申明(declaration)相關(guān)聯(lián)：
引用
1. 如果某單行文檔的最左邊是空格，它就和下面的申明關(guān)聯(lián)
2. 多個關(guān)聯(lián)到同一個申明的文檔會被連接在一起
3. 沒有關(guān)聯(lián)到申明的文檔會被忽略
4. 在module申明前的所有文檔會被應(yīng)用到整個模塊
5. 如果文檔出現(xiàn)在申明的右邊，則關(guān)聯(lián)到它
6. 如果文檔只是ditto，則應(yīng)用上一個申明的文檔
7. 如果一個申明沒有文檔，則不會出現(xiàn)在html輸出中，要出現(xiàn)，可以寫一個空的文檔，如 ///
看一個例子吧：
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; // 只有注釋，沒有文檔，不會出現(xiàn)在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;
文檔的節(jié)
a1.d例子中的Authors / Date 就是節(jié)(Sections)。
節(jié)由 "非空格字符" + ":" 組成，其中標識符部分叫節(jié)名，它不區(qū)分大小寫
概要(Summary)：
第一個節(jié)就是概要，它沒有節(jié)名；
它是第一個段落，遇到空行或者節(jié)名結(jié)束；
可以把概要寫成多行,但寫成一行比較好
概要節(jié)是可選的
描述(Description)：
第二個沒有名字的節(jié) 是描述
遇到一個節(jié)名或者到文檔的結(jié)束
給個例子(a4.d)：
Java代碼
- /***********************************
- * 這是一個概要(Brief summary)
- * 描述myfunch函數(shù)的使用；這兩行形成一個概要節(jié)
- *
- * 描述節(jié)的第一個段落
- *
- * 還是描述節(jié)：
- * 可以寫更多內(nèi)容
- */
- void myfunc() { }
html輸出【見附件 doc1/a4.html】：
Java代碼
- void myfunc();
- 這是一個概要(Brief summary) 描述myfunch函數(shù)的使用；這兩行形成一個概要節(jié)
- 描述節(jié)的第一個段落
- 還是描述節(jié)： 可以寫更多內(nèi)容
標準節(jié)
有一些預(yù)定義好了的節(jié)，看看它們的意思：
- Authors: 列出作者名字
- Bugs: 列出已知BUG
- Date: 列出當前修訂的時間，應(yīng)當是 std.date 能解析的形式
- Deprecated: 做 "抗議"標記(？棄用標記)--最好給出理由和糾正的方法
- Examples: 例子
- History: 修訂歷史
- License: 版權(quán)申明
- Returns: 解釋函數(shù)的返回值；如果返回void，就不要寫在文檔中了
- See_Also: 列出相關(guān)符號，或者URL鏈接
- Standards: 如果申明涉及到某個標準，在此描述
- Throws: 列出在哪些環(huán)境下會拋出異常
- Version: 指定當前申明的版本號
- See_Also: 列出相關(guān)符號，或者鏈接
- See_Also: 列出相關(guān)符號，或者鏈接
特殊節(jié)：一些有特殊含義和語法的節(jié)
- Copyright: 版權(quán)申明。如果是在module申明中，該節(jié)會被COPYRIGHT宏替換；
- Params: 函數(shù)的參數(shù)描述文檔； "標識符 =' 開始一個新的參數(shù)描述；它可以跨越多行
- 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 = 版權(quán)歸熱愛地球的火星人所有
- */
- /**
- * 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. 版權(quán)歸熱愛地球的火星人所有
上面的例子都還好理解，把不容易理解的說說：
/** Copyright: Public Domain */ 在module申明前和后的效果不一樣；
前者的效果在哪里？看頁面的最后一行
代碼的文檔是這么寫的：
Java代碼
- * Examples:
- * --------------------
- * writefln("3"); // writes '3' to stdout
- * --------------------
代碼的上下有一條分割線：至少三個連字符(-)
文檔的高亮處理
內(nèi)嵌注釋 Embedded Comments
不懂
內(nèi)嵌代碼 Embedded Code
上面已經(jīng)演示了
內(nèi)嵌的HTML Embedded HTML
內(nèi)嵌的HTML代碼不會被轉(zhuǎn)譯，直接輸出給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>
- */
強調(diào) Emphasis
函數(shù)參數(shù)等標識符會被以斜體，粗體，超鏈接等形式強調(diào)處理；具體形式文檔沒有說
特殊符號Character Entities
< > & 有特殊含義，如果要使用這3個符號，換成相應(yīng)的：< > &
以下情況除外：在代碼節(jié)中；不是立即跟一個 # 或 字母
文檔的宏
宏來自于下面這些地方，并按照特定步驟處理：
- 預(yù)定義宏
- sc.ini配置文件中的DDOCFILE項指定的文件
- 命令行指定的*.ddoc文件
- Ddoc運行時產(chǎn)生的定義，如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
假設(shè)要編譯: a5.d doc2/candydoc
Java代碼
- 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)
以上面的5個程序為例：
Java代碼
- 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
如果要用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
上面的配置只寫了candy.ddoc文件，沒有寫module.ddoc。所以編譯的時候要添加module.ddoc，這樣做很不爽；
我的辦法是自己寫一個.ddoc文件--proj.ddoc
把candydoc.ddoc和 module.ddoc兩個文件合并在一起
[模塊部分的導(dǎo)航要求所有的html都在一個目錄下，這點還沒有仔細研究，回頭再寫]
注意，如果沒有效果，檢查：
1. Linux是修改dmd.conf文件；Windows是修改sc.ini文件；不要弄錯了
2. dmd.conf 可能在多個地方：/etc 或 dmd命令所在目錄等
3. candy.doc是相對于當前目錄而已，不是dmd.conf文件；請按照實際情況設(shè)定路徑
文檔用起來還算簡單，開始會不習(xí)慣，慢慢就習(xí)慣了。
安徽新華電腦學(xué)校專業(yè)職業(yè)規(guī)劃師為你提供更多幫助【在線咨詢】
