为D源代码生成文档的candydoc命令

最新推荐文章于 2011-06-12 15:27:01 发布

最新推荐文章于 2011-06-12 15:27:01 发布 · 264 阅读

文章标签：

#D语言 #CSS #F# #HTML

Dlang小工具专栏收录该内容

2 篇文章

订阅专栏

本文介绍了一款基于CandyDoc的自动化文档生成工具，该工具简化了文档生成过程，仅需通过简单的命令行参数即可生成全面的文档，包括模块导航等内容。

背景：

使用CandyDoc生成文档时，
需要手动修改一些文件，
尤其是要在modules.docc中列出所有的模块，
以便在文档中提供导航的功能。

为了方便文档的生成，
有了做一个自动生成文档命令的想法，
不知道是否已经有结合CandyDoc自动生成文档的方法了，
就当是学习D语言一周的一个练习吧。

如果哪位朋友也需要这个工具(candydoc.exe)，
请随便下载后使用。

主要思想：
把使用CandyDoc时那些需要手动修改的内容让candydoc.exe去做，
只需要简单地输入“candydoc -src=srcpath”就可以完成文档的生成了。

解压缩下载包之后，
目录结构是这样：

写道

生成文档以后的目录结构：

写道

使用方法：

写道

Usage:
candydoc -src=srcpath {-switch}

-src=srcpath 指定D源代码的顶级目录(Require)
-Dd=docspath 指定文档输出目录, 默认:[.\docs]
-candy=candyfile 指定candy.ddoc, 默认:[.\docs\candydoc\candy.ddoc]
-module=modulesfile 指定modules.ddoc, 默认:[.\docs\candydoc\modules.ddoc]
--help 显示帮助信息

建议: 将candydoc.exe和docs目录放在同一个文件夹中，
          然后，运行candydoc命令，
          生成的文档(html)将出现在docs目录中。
注意：确保docs目录中存在candydoc文件夹，否则，生成的文档将没有theme。
例子: 【1】candydoc -src=D:\dmd_project\projectA\src
            对-src指定的源代码中的注释，在当前目录docs中生成文档。
例子: 【2】candydoc -src=..\..\src -Dd=..\docs
            对-src指定的源代码中的注释，在上级目录的docs中生成文档。

实战：

假设使用下面的D源代码：

module candydocsample;

/**
*CandyDoc例子
*Authors:Sinpool
*Date:2011-05-21 
*/
class CandyDocSample{
	
	/**
	*KEY(Code1)
	*/
	public static const string KEY_CODE1 = "key_code1";
	
	/**
	*KEY(Code2)
	*/
	public static const string KEY_CODE2 = "key_code2";
	
	/**
	*默认的构造函数。
	*/
	this(){
		//……
	}
	
	/**
	*获得文件ID。
	*Returns:
	*	返回文件ID
	*/
	public int getFileId(){
		//……
		return 0;
	}
	
	/**
	*设置文件ID。
	*Params:
	*	x_fileId = 文件ID
	*Examples:
	*	setFileId(10010)
	*/
	public void setFileId(int x_fileId){
		//……
	}
	
	/**
	*设置文件ID。
	*Params:
	*	x_fileId = 文件ID
	*Examples:
	*	setFileId("10010")
	*Deprecated:
	*	已经废弃，请使用setFileId(int x_fileId)
	*/
	public void setFileId(string x_fileId){
		//……
	}
}

生成的docs像下面这样：