Question

许多现代编程语言都支持将注释系统作为文档字符串。

此功能在Python或Clojure等语言中被视为理所当然，其中文档字符串可能有助于理解可能不清楚的函数的用途：

def gen_ast(s):
    ''' given a string, s, representing a program, generates object model of abstract syntax tree '''
    # function contents here ...

我在D编程方面相当新手，但还没有找到以客户端可访问的方式编写文档字符串注释的文档（例如，Python中的help(gen_ast)）。 D是否为文档字符串提供支持？

Answer 1

是

代码本身： http://dlang.org/spec/ddoc.html

对于命令行上的选项： http://dlang.org/phobos/std_getopt.html

从代码中获取： http://dlang.org/spec/attribute.html#uda

但是，公平地说，文档注释不能直接在代码中访问 - 您必须将其作为UDA或getopt库文档字符串来执行，或者在构建集中使用单独的命令来提取注释（dmd -D使它们成为html，dmd -D -X将它们变成json，然后你解析它）

Answer 2

作为@Adam D Ruppe的答案的后续内容，这里是从第一个链接中提取的相关内容，这是D文档生成的官方规范。

首先，返回的函数指定如下：

 /**
 * Read the file.
 * Returns: The contents of the file.
 */

void[] readFile(char[] filename) { ... }

其次，在需要时以类似的方式指定示例：

/**
 * Examples:
 * --------------------
 * writeln("3"); // writes '3' to stdout
 * --------------------
 */

但是，我发现文档在使用这些约定生成自动文档的能力方面不明确。

D是否支持文档生成？

2 个答案: