国产一区二区精品久久_蜜桃狠狠狠狠狠狠狠狠狠_午夜视频精品_激情都市一区二区

當(dāng)前位置：首頁 > 網(wǎng)站舊欄目 > 學(xué)習(xí)園地 > 設(shè)計(jì)軟件教程 > Ddoc文檔注釋學(xué)習(xí)筆記

Ddoc文檔注釋學(xué)習(xí)筆記
2010-01-13 22:52:58  作者:  來源:
Ddoc學(xué)習(xí)筆記

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

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


文檔有以下幾個(gè)步驟處理:
  1. 詞法 文檔注釋被 附加的記號(hào) 標(biāo)識(shí)..
  2. 解析 文檔注釋 被關(guān)聯(lián)到 特殊的定義和組合
  3. 段落 每個(gè)文檔注釋 被 分解到一個(gè)段落的序列
  4. 處理特定的節(jié).
  5. 非特殊的段落完成后高亮顯示.
  6. 合并模塊中的所有段落.
  7. 在最終結(jié)果執(zhí)行宏文本替換.


下面按照這個(gè)順序來展開；

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


文檔的語法

從一個(gè)最簡單的程序開始吧：

Java代碼 復(fù)制代碼
  1. /**  
  2.  * 這個(gè)一個(gè)Ddoc文檔例子  
  3.  *   
  4.  * Authors: Dehong Liu  
  5.  * Date:    2007年8月13日  
  6.  */  
  7.   
  8. void main()   
  9. {   
  10. }  

注意注釋符號(hào) /**，和單詞Authors/Date。

編譯這個(gè)文件(a1.d)，并且生成文檔doc1/a1.html
Java代碼 復(fù)制代碼
  1. dmd -Dddoc1 a1.d            # -DdXXX 指定文檔生成路徑為XXX  

用瀏覽器打開這個(gè)html文件，看起來像下面這樣【見附件 doc1/a1.html】：
Java代碼 復(fù)制代碼
  1. a1   
  2.   
  3. void main();   
  4.     這個(gè)一個(gè)Ddoc文檔例子   
  5.   
  6.     Authors:   
  7.     Dehong Liu   
  8.   
  9.     Date:   
  10.     2007年8月13日    
  11.   
  12. -------------------------------------------------------------      
  13. Page generated by Ddoc.   

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

現(xiàn)在一個(gè)個(gè)開始解釋。
文檔有下面三種寫法：
Java代碼 復(fù)制代碼
  1.   
  2. /** ...   */        / 后面兩個(gè)*    
  3. /++ ...   +/        / 后面兩個(gè)+   
  4. ///                 三個(gè) /      


下面有一個(gè)完整的文檔寫法例子（a2.d）：
Java代碼 復(fù)制代碼
  1. /// 這是一個(gè)行文檔注釋   
  2.   
  3. /** 這也是 */  
  4.   
  5. /++ 同樣 +/   
  6.   
  7. /**  
  8.    這是一個(gè)摘要文檔  
  9.  */  
  10.   
  11. /**  
  12.  * 開頭的* 不是文檔的一部分  
  13.  */  
  14.   
  15. /*********************************  
  16.    在 /** 后面的連續(xù)的*，  
  17.    不是文檔的一部分  
  18.  */  
  19.   
  20. /++   
  21.    這也是一個(gè)摘要文檔   
  22.  +/   
  23.   
  24. /++   
  25.  + 開頭的+ 不是文檔的一部分   
  26.  +/   
  27.   
  28. /+++++++++++++++++++++++++++++++++   
  29.    在 ／++ 后面的連續(xù)的+，   
  30.    不是文檔的一部分   
  31.    上面的斜杠是中文符號(hào)，避免語法錯(cuò)誤   
  32.   
  33.    換行：注意上面的空行   
  34.  +/   
  35.   
  36. /*********** 前面連續(xù)的*號(hào)不是，這部分*****是文檔，后面的又不是  *****************/  
  37.   
  38. module a2;  


輸出的html結(jié)果【見附件 doc1/a2.html】：
Java代碼 復(fù)制代碼
  1. a2   
  2. 這是一個(gè)行文檔注釋   
  3.   
  4. 這也是   
  5.   
  6. 同樣   
  7.   
  8.   
  9.   
  10. 這是一個(gè)摘要文檔   
  11.   
  12.   
  13.   
  14. 開頭的* 不是文檔的一部分   
  15.   
  16.   
  17.   
  18. 在 /** 后面的連續(xù)的*， 不是文檔的一部分   
  19.   
  20.   
  21.   
  22. 這也是一個(gè)摘要文檔   
  23.   
  24.   
  25.   
  26. 開頭的+ 不是文檔的一部分   
  27.   
  28.   
  29.   
  30. 在 ／++ 后面的連續(xù)的+， 不是文檔的一部分 上面的斜杠是中文符號(hào)，避免語法錯(cuò)誤   
  31.   
  32. 換行：注意上面的空行   
  33.   
  34. 前面連續(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. 沒有關(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è)申明沒有文檔，則不會(huì)出現(xiàn)在html輸出中，要出現(xiàn)，可以寫一個(gè)空的文檔，如 ///
 


看一個(gè)例子吧：
Java代碼 復(fù)制代碼
  1. /**  
  2.  * 整個(gè)模塊的文檔  
  3.  */  
  4.   
  5. module a3;   
  6.   
  7. int a;  /// a;的文檔，b沒有文檔   
  8. int b;   
  9.   
  10. /** c和d的文檔 */  
  11. /** 再添加些c和d的文檔的文檔 */  
  12. int c;   
  13. /** ditto */  
  14. int d;   
  15.   
  16. /** e和f的文檔 */ int e;   
  17. int f;  /// ditto   
  18.   
  19. /** g的文檔 */  
  20. int g; /// 在添加點(diǎn)g的文檔   
  21.   
  22. /// C和D的文檔   
  23. class C   
  24. {   
  25.     int x;    /// C.x的文檔   
  26.   
  27.     /** C.y 和 C.z的文檔 */  
  28.     int y;   
  29.     int z;    /// ditto   
  30. }   
  31.   
  32. /// ditto   
  33. class D   
  34. {   
  35. }   
  36.   
  37. int h; // 只有注釋，沒有文檔，不會(huì)出現(xiàn)在html中   
  38.   
  39. // 下面是空文檔   
  40. int j; ///    
  41.   
  42. /// 被忽略的文檔  


看起來像這樣【見附件 doc1/a3.html】
Java代碼 復(fù)制代碼
  1. a3   
  2. 整個(gè)模塊的文檔   
  3.   
  4. int a;   
  5.     a;的文檔，b沒有文檔   
  6.   
  7. int c;   
  8. int d;   
  9.     c和d的文檔   
  10.   
  11.     再添加些c和d的文檔的文檔   
  12.   
  13. int e;   
  14. int f;   
  15.     e和f的文檔   
  16.   
  17. int g;   
  18.     g的文檔   
  19.   
  20.     在添加點(diǎn)g的文檔   
  21.   
  22. class C;   
  23. class D;   
  24.     C和D的文檔   
  25.   
  26.     int x;   
  27.         C.x的文檔   
  28.   
  29.     int y;   
  30.     int z;   
  31.         C.y 和 C.z的文檔   
  32.   
  33. int j;  



文檔的節(jié)

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

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

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

給個(gè)例子(a4.d)：
Java代碼 復(fù)制代碼
  1. /***********************************  
  2.  * 這是一個(gè)概要(Brief summary)  
  3.  * 描述myfunch函數(shù)的使用；這兩行形成一個(gè)概要節(jié)  
  4.  *  
  5.  * 描述節(jié)的第一個(gè)段落  
  6.  *  
  7.  * 還是描述節(jié)：  
  8.  * 可以寫更多內(nèi)容  
  9.  */  
  10.   
  11. void myfunc() { }  

html輸出【見附件 doc1/a4.html】：
Java代碼 復(fù)制代碼
  1. void myfunc();   
  2.     這是一個(gè)概要(Brief summary) 描述myfunch函數(shù)的使用；這兩行形成一個(gè)概要節(jié)   
  3.   
  4.     描述節(jié)的第一個(gè)段落   
  5.   
  6.     還是描述節(jié)： 可以寫更多內(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，就不要寫在文檔中了
  • 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é)：一些有特殊含義和語法的節(jié)
  • Copyright: 版權(quán)申明。如果是在module申明中，該節(jié)會(huì)被COPYRIGHT宏替換；
  • Params: 函數(shù)的參數(shù)描述文檔； "標(biāo)識(shí)符 =' 開始一個(gè)新的參數(shù)描述；它可以跨越多行
  • Macros: 和Params節(jié)有類似的語法；它是一系列 NAME=value 組成 NAME 是宏名，VALUE是要替換成的文字
     


全部列出來看看：
Java代碼 復(fù)制代碼
  1. /** Copyright: Public Domain */  
  2.   
  3. module a5;   
  4.   
  5. /**  
  6.  * Authors: Melvin D. Nerd, melvin@mailinator.com  
  7.  *  
  8.  * Bugs: Doesn't work for negative values.  
  9.  *  
  10.  * Date: March 14, 2003  
  11.  */  
  12.   
  13. void foo1() {}   
  14.   
  15. /**  
  16.  * Deprecated: superseded by function bar().  
  17.  */  
  18.   
  19. deprecated void foo2() {  }   
  20.   
  21. /**  
  22.  * Examples:  
  23.  * --------------------  
  24.  * writefln("3"); // writes '3' to stdout  
  25.  * --------------------  
  26.  *  
  27.  * History:  
  28.  *  V1 is initial version  
  29.  *  
  30.  *  V2 added feature X  
  31.  *  
  32.  * License: use freely for any purpose  
  33.  */  
  34.   
  35. void bar() { }   
  36.   
  37. /**  
  38.  * Read the file.  
  39.  * Returns: The contents of the file.  
  40.  */  
  41.   
  42. void[] readFile(char[] filename) { return "filename"; }   
  43.   
  44. /**  
  45.  * See_Also:  
  46.  *    foo, bar, http://www.digitalmars.com/d/phobos/index.html  
  47.  *  
  48.  * Standards: Conforms to DSPEC-1234  
  49.  *  
  50.  * Throws: WriteException on failure.  
  51.  *  
  52.  * Version: 1.6a  
  53.  */  
  54.   
  55. void writeFile(char[] filename) {  }   
  56.   
  57. // 特殊節(jié)   
  58.   
  59. /***********************************  
  60.  * foo does this.  
  61.  * Params:  
  62.  *  x = is for this  
  63.  *      and not for that  
  64.  *  y = is for that  
  65.  */  
  66.   
  67. void foo(int x, int y)   
  68. {   
  69. }   
  70.   
  71. /**  
  72.  * Macros:  
  73.  *  FOO =   now is the time for  
  74.  *      all good men  
  75.  *  BAR =   bar  
  76.  *  MAGENTA =   <font color=magenta></font>  
  77.  *  COPYRIGHT = 版權(quán)歸熱愛地球的火星人所有  
  78.  */  
  79.   
  80. /**  
  81.  * Foo: $(FOO)  
  82.  * Bar: $(BAR)  
  83.  * MAGENTA: $(MAGENTA)  
  84.  * Copyright: Public Domain   
  85.  */  
  86. void foo3() {   }  

輸出效果是【見附件doc1/a5.html】：
Java代碼 復(fù)制代碼
  1. a5   
  2.   
  3. void foo1();   
  4.     Authors:   
  5.     Melvin D. Nerd, melvin@mailinator.com   
  6.   
  7.     BUGS:   
  8.     Doesn't work for negative values.   
  9.   
  10.     Date:   
  11.     March 14, 2003  
  12.   
  13. deprecated void foo2();   
  14.     Deprecated:   
  15.     superseded by function bar().   
  16.   
  17. void bar();   
  18.     Examples:   
  19.   
  20.      writefln("3"); // writes '3' to stdout   
  21.   
  22.   
  23.   
  24.     History:   
  25.     V1 is initial version   
  26.   
  27.     V2 added feature X   
  28.   
  29.     License:   
  30.     use freely for any purpose   
  31.   
  32. void[] readFile(char[] filename);   
  33.     Read the file.   
  34.   
  35.     Returns:   
  36.     The contents of the file.   
  37.   
  38. void writeFile(char[] filename);   
  39.     See Also:   
  40.     foo, bar, http://www.digitalmars.com/d/phobos/index.html   
  41.   
  42.     Standards:   
  43.     Conforms to DSPEC-1234  
  44.   
  45.     Throws:   
  46.     WriteException on failure.   
  47.   
  48.     Version:   
  49.     1.6a   
  50.   
  51. void foo(int x, int y);   
  52.     foo does this.   
  53.   
  54.     Params:   
  55.     int x   is for this and not for that   
  56.     int y   is for that   
  57.   
  58. void foo3();   
  59.     Foo:   
  60.     now is the time for all good men   
  61.   
  62.     Bar:   
  63.     bar   
  64.   
  65.     MAGENTA:   
  66.     <font color=magenta></font>   
  67.   
  68.     Copyright:   
  69.     Public Domain   
  70.   
  71. Page generated by Ddoc. 版權(quán)歸熱愛地球的火星人所有   


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

代碼的文檔是這么寫的：
Java代碼 復(fù)制代碼
  1. * Examples:     
  2. * --------------------     
  3. * writefln("3"); // writes '3' to stdout     
  4. * --------------------    

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

文檔的高亮處理

內(nèi)嵌注釋 Embedded Comments
不懂

內(nèi)嵌代碼 Embedded Code
上面已經(jīng)演示了

內(nèi)嵌的HTML Embedded HTML
內(nèi)嵌的HTML代碼不會(huì)被轉(zhuǎn)譯，直接輸出給html文件
雖然如此，基于某些原因（我沒看懂），還是最好不要用html
Java代碼 復(fù)制代碼
  1. /** Example of embedded HTML:  
  2.  *     
  3.  *      <li> <a href="http://www.digitalmars.com">Digital Mars</a> </li>  
  4.  *      <li> <a href="http://www.classicempire.com">Empire</a> </li>  
  5.  */  


強(qiáng)調(diào) Emphasis
函數(shù)參數(shù)等標(biāo)識(shí)符會(huì)被以斜體，粗體，超鏈接等形式強(qiáng)調(diào)處理；具體形式文檔沒有說

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

文檔的宏

宏來自于下面這些地方，并按照特定步驟處理：
  1. 預(yù)定義宏
  2. sc.ini配置文件中的DDOCFILE項(xiàng)指定的文件
  3. 命令行指定的*.ddoc文件
  4. Ddoc運(yùn)行時(shí)產(chǎn)生的定義，如BODY,TITLE
  5. 文件中的宏節(jié)


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

CandyDoc的使用

dmd默認(rèn)的格式很簡單，可以使用CandyDoc來美化文檔格式和增強(qiáng)功能。
使用方法很簡單：(.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代碼 復(fù)制代碼
  1. 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代碼 復(fù)制代碼
  1. MODULES =    
  2.     $(MODULE helix.basic)   
  3.     $(MODULE helix.color)   
  4.     $(MODULE helix.config)   
  5.     $(MODULE helix.linalgebra)  


以上面的5個(gè)程序?yàn)槔?
Java代碼 復(fù)制代碼
  1. MODULES =   
  2.     $(MODULE a.a1)   
  3.     $(MODULE a.a2)   
  4.     $(MODULE a.a3)   
  5.     $(MODULE a.a4)   
  6.     $(MODULE a.a5)  

編譯之：
Java代碼 復(fù)制代碼
  1. dmd -c -Dddoc2 a1 a2 a3 a4 a5.d doc2/candydoc/*.ddoc  


如果要用Candydoc替換默認(rèn)的文檔格式，這么做：
修改dmd.conf文件，添加一行：
DDOCFILE=candy.ddoc
看起來像這樣
Java代碼 復(fù)制代碼
  1. [Environment]   
  2. DFLAGS=-I%@P%/../src/phobos -L-L%@P%/../lib -L-L/usr/lib -L-L/usr/local/lib -version=Phobos   
  3. DDOCFILE=candy.ddoc  


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

[模塊部分的導(dǎo)航要求所有的html都在一個(gè)目錄下，這點(diǎn)還沒有仔細(xì)研究，回頭再寫]

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


文檔用起來還算簡單，開始會(huì)不習(xí)慣，慢慢就習(xí)慣了。

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