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

當前位置：首頁 > 網站舊欄目 > 學習園地 > 設計軟件教程 > Ddoc文檔注釋學習筆記

Ddoc文檔注釋學習筆記
2010-01-13 22:52:58  作者:  來源:
Ddoc學習筆記

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

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


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


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

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


文檔的語法

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

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

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

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

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

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

現在一個個開始解釋。
文檔有下面三種寫法：
Java代碼 復制代碼
  1.   
  2. /** ...   */        / 后面兩個*    
  3. /++ ...   +/        / 后面兩個+   
  4. ///                 三個 /      


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


輸出的html結果【見附件 doc1/a2.html】：
Java代碼 復制代碼
  1. a2   
  2. 這是一個行文檔注釋   
  3.   
  4. 這也是   
  5.   
  6. 同樣   
  7.   
  8.   
  9.   
  10. 這是一個摘要文檔   
  11.   
  12.   
  13.   
  14. 開頭的* 不是文檔的一部分   
  15.   
  16.   
  17.   
  18. 在 /** 后面的連續的*， 不是文檔的一部分   
  19.   
  20.   
  21.   
  22. 這也是一個摘要文檔   
  23.   
  24.   
  25.   
  26. 開頭的+ 不是文檔的一部分   
  27.   
  28.   
  29.   
  30. 在 ／++ 后面的連續的+， 不是文檔的一部分 上面的斜杠是中文符號，避免語法錯誤   
  31.   
  32. 換行：注意上面的空行   
  33.   
  34. 前面連續的*號不是，這部分*****是文檔，后面的又不是   



文檔和申明關聯

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

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


看一個例子吧：
Java代碼 復制代碼
  1. /**  
  2.  * 整個模塊的文檔  
  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; /// 在添加點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; // 只有注釋，沒有文檔，不會出現在html中   
  38.   
  39. // 下面是空文檔   
  40. int j; ///    
  41.   
  42. /// 被忽略的文檔  


看起來像這樣【見附件 doc1/a3.html】
Java代碼 復制代碼
  1. a3   
  2. 整個模塊的文檔   
  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.     在添加點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;  



文檔的節

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

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

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

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

html輸出【見附件 doc1/a4.html】：
Java代碼 復制代碼
  1. void myfunc();   
  2.     這是一個概要(Brief summary) 描述myfunch函數的使用；這兩行形成一個概要節   
  3.   
  4.     描述節的第一個段落   
  5.   
  6.     還是描述節： 可以寫更多內容   



標準節

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


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


全部列出來看看：
Java代碼 復制代碼
  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. // 特殊節   
  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 = 版權歸熱愛地球的火星人所有  
  78.  */  
  79.   
  80. /**  
  81.  * Foo: $(FOO)  
  82.  * Bar: $(BAR)  
  83.  * MAGENTA: $(MAGENTA)  
  84.  * Copyright: Public Domain   
  85.  */  
  86. void foo3() {   }  

輸出效果是【見附件doc1/a5.html】：
Java代碼 復制代碼
  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. 版權歸熱愛地球的火星人所有   


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

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

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

文檔的高亮處理

內嵌注釋 Embedded Comments
不懂

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

內嵌的HTML Embedded HTML
內嵌的HTML代碼不會被轉譯，直接輸出給html文件
雖然如此，基于某些原因（我沒看懂），還是最好不要用html
Java代碼 復制代碼
  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.  */  


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

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

文檔的宏

宏來自于下面這些地方，并按照特定步驟處理：
  1. 預定義宏
  2. sc.ini配置文件中的DDOCFILE項指定的文件
  3. 命令行指定的*.ddoc文件
  4. Ddoc運行時產生的定義，如BODY,TITLE
  5. 文件中的宏節


宏主要用在對文檔格式的自定義上。
通過修改宏，能自定義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代碼 復制代碼
  1. dmd -c -Dddoc2 a5.d doc2/candydoc/*.ddoc  

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

candydoc有2個.ddoc文件：candy.ddoc  modules.ddoc
如果要定義樣式，在candy.ddoc中定義，一般不改；
modules.ddoc 要修改成自己的模塊，默認是：
Java代碼 復制代碼
  1. MODULES =    
  2.     $(MODULE helix.basic)   
  3.     $(MODULE helix.color)   
  4.     $(MODULE helix.config)   
  5.     $(MODULE helix.linalgebra)  


以上面的5個程序為例：
Java代碼 復制代碼
  1. MODULES =   
  2.     $(MODULE a.a1)   
  3.     $(MODULE a.a2)   
  4.     $(MODULE a.a3)   
  5.     $(MODULE a.a4)   
  6.     $(MODULE a.a5)  

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


如果要用Candydoc替換默認的文檔格式，這么做：
修改dmd.conf文件，添加一行：
DDOCFILE=candy.ddoc
看起來像這樣
Java代碼 復制代碼
  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。所以編譯的時候要添加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文件；請按照實際情況設定路徑


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

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