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