D菜谱0710

用d文档文档化你代码

为验证你代码正确工作,你必须知道它该干啥.类似单元测试,D有个叫d文档的内置文档生成器.d文档很简单,但它完成工作并总可用.

如何做...

采取如下步骤到文档化你代码:

在他们上通过写/**文档*/或/++文档+/在他们后或用///直接简短描述来附加文档注释到声明.

在集合和成员上放文档注释.比如,如你文档一个类成员,确保在类其自身上也有文档注释.

文档化你想作为用例的单元测试.

文档化函数形参通过以格式写行:在节形参下的名=意思:.

用-D标志编译模块到dmd来生成文档的超文本文件.

你可定义并用宏.把他们定义在特殊节命名的宏:用名=值语法并带$(名)语法使用来扩展d文档的文字功能.

移动你跨许多模块用的宏到带.d文档扩展的单独文件并当生成文档时把它传递到编译器.

如下是如何用d文档来文档化对象的例子:

如你命名文件d文档.d,编译用:

生成的超文本(d文档.超文本)在浏览器上像这样:

这个屏幕截图使用默认超文本体并没有CSS风格表格.你可用超文本和CSS通过改变D文档宏来连接到外部文件来自定义网站的外观.

它如何工作...

D语言和编译器有个内置的有简单语法,易用,且熟悉语言的文档工具.感谢语言的整合,d文档注释不必重复代码中已很明显的信息.

d文档几乎没有内置语法.一个文档注释包含四个部分:

一个总是第一行的行总述.

一个多行描述,在第一行后,但在任何标签节前的内容.

第三部分是以标签和冒号开头的节.节,形参的:是特别的,因为它也解析名=描述行.宏:是特别因为它在名=替代中格式解析新宏.其他节名用于不改变d文档的解析的组织内容.

第四部分是一直有的宏.

宏是d文档为了扩展和自定义的工具.一个宏通过文字替代工作且语法如下:$(宏_名 参1,参2,...).宏可跨多行.定义所有d文档的默认输出为宏.你可在由dmdzip发布的源码中见到默认.文件是dmd2/源/dmd/文档.c,例如,在宏D文档中定义默认超文本体.

你可在你独立文件(在你模块顶部的节)或当生成文档时你传递给dmd的带个带.d文档的扩展单独文件中覆盖这个宏.造一个宏

提示

允许并忽略开头的星或加号:

这将让你按你想的格式化注释而不必影响内容.

d文档没有适当为输出格式加密特殊字符.为解决它,你可用宏替换特殊字符,例如,当生成超文本时用$(GT)而不是>.

宏语法在替代文本时有三种特殊形式:$0,其是所有实参作为单个串;$1..$n,其是一个特殊实参;和$+,其是除了第一个的所有实参.用$1和$+,我们可创建递归宏来模拟循环:

宏:

更多...

如在单元测试中例子,故意最小化内置功能来提供没理由不用的基准行.当需要附加特征,我们会找第三方文档工具.

dmd有一对开关来帮我们:-X和-D.-X开关生成一个列举它编译的所有声明的数据串格式文件.-D开关生成文档.如果你组合他们两个,数据串格式文件也包含附加到每个声明的文档注释.这使他们易于解析-不必写个新编译器,因为一个数据串格式解析器就够了.