每一个文档都和一个声明(declaration)相关联,原则:
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; ///
/// 被忽略的文档
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; ///
/// 被忽略的文档