为D源代码生成文档的CandyDoc使用方法

既然要学习D语言，

就需要用D语言去写点东西。

 

写东西的话，

一定会用到注释，

当然，对于一些自己整理的工具类，

也有必要导出文档，

方便以后查看。

 

看了D语言的介绍，

DMD编译器本身支持创建文档的参数“-D”，

而且，

文档注释的方法与JavaDoc的方法也比较类似，

所以，很快就可以使用了。

 

但是，

利用DMD生成的文档画面很“傻”，

一点也不活泼，

找到了一个叫“CandyDoc”的工具，

可以结合DMD生成带导航页的文档，

而且，提供了默认的css，

画面也比较好看。

 

下面记录了使用CandyDoc的方法，

以便日后查阅。

 

1、在D源代码中追加文档注释的方法。

http://www.digitalmars.com/d/2.0/ddoc.html

 

注释必须以“/**”开头。

 

常用的一些标记是：

常用标记 写道

Authors: 作者
Date: 日期
Deprecated: 废弃的
Params: 参数名=参数的描述
Returns:返回值的描述

 

 

2、例子

分别有两个D源文件，

目录结构是：

目录结构 写道

.\src\Main.d
.\src\sinpool\utils\splutils.d

 

module Main;

import std.stdio;
import sinpool.utils.splutils;

/**
* 练习
* Params: args=命令行参数
* Returns: 结束状态(0:正常结束)
*/
int main(string[] args){
	writeln("===>",SplUtils.isEmpty("\tt"));
	return 0;
}

 

module sinpool.utils.splutils;

import std.string;
import std.stdio;

/**
* 这是工具类
*Authors: sinpool
*Date: 2011-05-21
*/
public class SplUtils{
	
	/**
	*判断字符串是否为空。
	*Params: x_str=需要判断的字符串
	*Returns: 是空返回true，否则返回false
	*/
	public static bool isEmpty(string x_str){
		if (isEmpty2(x_str)){
			return true;
		}
		
		string p_str = x_str;
		p_str = tr(p_str," ","");
		p_str = tr(p_str,"　","");
		p_str = tr(p_str,"\t","");
		p_str = strip(p_str);
		
		return isEmpty2(p_str);
	}
	
	/**
	*判断字符串是否为空。
	*Params: x_str=需要判断的字符串
	*Returns: 是空返回true，否则返回false
	*/
	public static bool isEmpty2(string x_str){
		
		string p_str = x_str;
		p_str = chop(p_str); // 去掉结尾符(\0、CR、CR-LF)
		
		if ( p_str==null ){
			return true;
		}
		if ( p_str=="" ){
			return true;
		}
		
		return false;
	}
}

 

注：

有定义class时，

一定要为class写一段文档注释，

否则，

不能将该module中的注释导出为文档。

 

3、CandyDoc的使用

从官网下载CandyDoc。

http://www.dsource.org/projects/helix/wiki/CandyDoc

 

解压缩后，查看CANDYDOC.txt文件，

里面记述了使用方法。

 

我使用了很多的默认theme，

基本没有作什么修改。

 

我准备把文档生成到src\docs中，

所以，目前的目录结构变成了下面这样：

目录结构 写道

.\src\Main.d
.\src\sinpool\utils\splutils.d
.\src\docs

 

①

将解压缩后的candydoc目录复制到要生成文档的目录。

我放到了“.\src\docs”里。

②

修改candydoc\modules.ddoc文件，

将要生成文档的包和module写进去。

修改后的样子是：

写道

MODULES =
$(MODULE .Main)
$(MODULE sinpool.utils.splutils)

 

因为只生成两个module的文档，

所以，就把他们写上。

第一行的“.Main”，

是指在src目录中的Main.d文件。

 

目前的目录结构变成了：

目录结构 写道

.\src\Main.d
.\src\sinpool\utils\splutils.d
.\src\docs\candydoc

 

③

结合CandyDoc配置文件，

运行带“-D”参数的dmd命令，

以便生成具有CandyDoc风格的文档。

进入src目录，运行下面的命令：

写道

dmd Main.d sinpool\utils\splutils.d docs\candydoc\candy.ddoc docs\candydoc\modules.ddoc -D -Dddocs

注：

如果要生成很多源代码对应的文档，

估计要写一个脚本，

或者找找其他的辅助工具进行使用了。 

 

4、效果

至此，

在src\docs下面会生成html的文档。

 

下面是生成的“sinpool\utils\splutils”的样子：