ddoc

1. 如果某单行文档的最左边是空格，它就和后面紧邻的声明关联 
2. 多个关联到同一个声明的文档会被连接在一起 
3. 没有关联到声明的文档会被忽略 
4. 在module声明前的所有文档会被应用到整个模块 
5. 如果文档出现在声明的右边，则关联到这个声明 
6. 如果文档只是ditto，则使用上一个声明的文档，ditto表示同上的意思
7. 如果一个声明没有文档，则不会出现在html输出中，要出现，可以写一个空的文档，如///
8 .调用命令“dmd main.d -D”对文件main.d生成ddoc文档。dmd默认的格式很简单，可以使用CandyDoc来美化文档格式和增强功能。 

节（section）由 "非空格字符" + ":" 组成，其中标识符部分叫节名，它不区分大小写 


概要(Summary)： 
第一个节就是概要，它没有节名； 
它是第一个段落，遇到空行或者节名结束； 
可以把概要写成多行,但写成一行比较好 
概要节是可选的 


描述(Description)： 
第二个没有名字的节 是描述 
遇到一个节名或者到文档的结束 


标准节：有一些预定义好了的节，如下
Authors: 列出作者名字
Bugs: 列出已知BUG
Date: 列出当前修订的时间，应当是 std.date 能解析的形式
Deprecated: 做 "抗议"标记(？弃用标记)--最好给出理由和纠正的方法
Examples: 例子
History: 修订历史
License: 版权申明
Returns: 解释函数的返回值；如果返回void，就不要写在文档中了
See_Also: 列出相关符号，或者URL链接
Standards: 如果申明涉及到某个标准，在此描述
Throws: 列出在哪些环境下会抛出异常
Version: 指定当前申明的版本号


特殊节：一些有特殊含义和语法的节 
Copyright: 版权申明。如果是在module申明中，该节会被COPYRIGHT宏替换；
Params: 函数的参数描述文档； "标识符 =' 开始一个新的参数描述；它可以跨越多行
Macros: 和Params节有类似的语法；它是一系列 NAME=value 组成 NAME 是宏名，VALUE是要替换成的文字 

/**  
* 对整个模块的描述
*/
module main;


import std.stdio;


int main(string[] argv)
{
    writeln("Hello D-World!");


    docDemo(0, 0);


    getchar();
    return 0;
}


int doc1; /// ddoc的三种形式
int doc2; /** ditto   */
int doc3; /++ ditto   +/


/**  
* 函数的功能  
*   
* Authors: Melvin D. Nerd, melvin@mailinator.com


* Bugs: 负数值不工作


* Date: March 14, 2003


* Deprecated: 由函数 bar() 所取代


* Params:
* x = 这个而不是那个
* y = 是那个


* Examples:
* writefln("3"); // 输出 '3' 到标准输出


* History:
* V1 是原始版本
* V2 添加了功能 X
*
* License: 随意使用于任何目的


* Returns: 文件内容


* Throws: WriteException 异常，在失败时


* See_Also: foo, bar, http://www.digitalmars.com/d/phobos/index.html


* Standards: 符合 DSPEC-1234


* Version: 1.6a


* Copyrights: 公共领域(Public Domain)
*/ 
int docDemo(int x, int y)
{
    int a; /// 这句不会生成文档，因为是函数内的变量


    return 0;
}


// 全局变量
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 的文档（注意只有当该类有doc时其成员的doc才会出现在html中）
    /** C.y 和 C.z 的文档 */
    int y;
    int z; /// ditto


    /**  
    * 判断字符串是否为空。  
    * Params: s = 字符串  
    * Returns: 是空返回true，否则返回false  
    */
    public static bool isEmtpy(string s)
    {
        return true;
    }


}
/// ditto
class D { }


int h; // 只有注释，没有文档，不会出现在html中   


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


/// 被忽略的文档 

转载于:https://my.oschina.net/u/3485339/blog/900369