Erlang EDoc

Posted on   |  

the Erlang program documentation generator.

Introduction

EDoc是使用@Name的标签来编写Erlang文档。如果源文件中不包含任何EDoc标签，EDoc只能从模块中提取基本信息。
EDoc标签必须出现在注释行，注释行必须在程序声明行之间(EDoc标签不能和代码处于同一行)。
%% @doc 打印XX正确的EDoc标签
% % @doc 打印XX错误，因为第一个% 会忽略后续出现的内容

Running EDoc

edoc:file/2(from EDoc version 0.1)已被弃用，不应继续使用。
edoc:application/2为Erlang应用创建文档。
edoc:files/2为指定源文件创建文档。
edoc:run/2通用接口，是edoc:files/2的加强版。

EDoc API详细说明–>EDoc API

overview.edoc

当为Erlang应用生成文档时，需要生成应用文档的首页(概述页面)，文档的首页(概述页面)则是通过EDoc目标目录(默认./doc)中的overview.edoc文件生成的。
文档中的详细信息则是通过源文件中的EDoc标签自动生成的。

overview.edoc的格式与EDoc标签相同，只是每行开头没有%字符，第一个出现EDoc标签的行视为开始，之前的行全部为注释:

1
2
3
4
5
6
7
8
** this is the overview.doc file for the application 'frob' **

@author R. J. Hacker <rjh@acme.com>
@copyright 2007 R. J. Hacker
@version 1.0.0
@title Welcome to the `frob' application!
@doc `frob' is a highly advanced frobnicator with low latency,
...

EDoc标签

可在overview.edoc中使用的EDoc标签

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
%% @author Richard Carlsson
%% @author Richard Carlsson <carlsson.richard@gmail.com>
%%   [http://user.it.uu.se/~richardc/]
%% @author <carlsson.richard@gmail.com>
%% @author carlsson.richard@gmail.com [http://user.it.uu.se/~richardc/]

%% @copyright 2001-2003 Richard Carlsson

%% @doc This is a <em>very</em> useful module. It is ...

%% @reference Pratchett, T., <em>Interesting Times</em>,
%% Victor Gollancz Ltd, 1994.
%% @reference See <a href="www.google.com">Google</a> for
%% more information.

%% 引用模块，函数，数据类型或者Erlang应用
%% @see edoc
%% @see edoc.<b>EDoc</b>

%% 指定何时引用模块，内容可以是任意文本
%% @since

%% @title 这个只能在 overview.edoc 中使用

%% 指定模块版本，内容可以是任意文本
%% @version

可在模块声明之前使用的EDoc标签

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
%% @author Richard Carlsson
%% @author Richard Carlsson <carlsson.richard@gmail.com>
%%   [http://user.it.uu.se/~richardc/]
%% @author <carlsson.richard@gmail.com>
%% @author carlsson.richard@gmail.com [http://user.it.uu.se/~richardc/]

%% @copyright 2001-2003 Richard Carlsson

%% @deprecated Please use the module {@link foo} instead.

%% @doc This is a <em>very</em> useful module. It is ...

%% @hidden 隐藏，这段不会出现在文档中，EDoc会忽略这个标签

%% @private 私有，如果生成私有文档，这段会出现，否则EDoc会忽略这个标签

%% @reference Pratchett, T., <em>Interesting Times</em>,
%% Victor Gollancz Ltd, 1994.
%% @reference See <a href="www.google.com">Google</a> for
%% more information.

%% 引用模块，函数，数据类型或者Erlang应用
%% @see edoc
%% @see edoc.<b>EDoc</b>

%% 指定何时引用模块，内容可以是任意文本
%% @since

%% 指定模块版本，内容可以是任意文本
%% @version

可在函数声明之前使用的EDoc标签

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
%% @deprecated Please use the module {@link foo} instead.

%% @doc 以第一个句号 . 或者感叹号 ! 后接空格或者换行作为结束 .

%% 指定与另一个函数的等价性，内容必须是正确的Erlang表达式
%% @equiv 

%% @hidden 隐藏，这段不会出现在文档中，EDoc会忽略这个标签

%% 提供函数的单个参数的更多信息
%% 由参数名称，后接一个或多个空格符和XHTML文本组成
%% @param

%% @private 私有，如果生成私有文档，这段会出现，否则EDoc会忽略这个标签

%% 指定函数返回值，内容由XHTML文本组成
%% @returns

%% 引用模块，函数，数据类型或者Erlang应用
%% @see edoc
%% @see edoc.<b>EDoc</b>

%% 指定何时引用模块，内容可以是任意文本
%% @since

%% 指定函数可能抛出的Term类型
%% @throws

%% 使用 -type 代替
%% @type

%% 使用 -spec 代替
%% @spec

可在任何地方使用的EDoc标签

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
%% clear 通常在条件编译时使用
%% 当DEBUG未定义时
%% clear能保证不会出现两个doc
-ifdef(DEBUG).
%% @doc ...
foo(...) -> ...
-endif.
%% @clear
%% @doc ...
bar(...) -> ...

%% ----------------------------------
%% ...
%% @doc ...
%% ...
%% @end
%% ----------------------------------

%% 读取一个 overview.edoc 格式的文件
%% @docfile

%% 读取一个 xx.hrl 的文件
%% @headerfile

%% @TODO Finish writing the documentation.
%% @todo Implement <a href="http://www.ietf.org/rfc/rfc2549.txt">RFC 2549</a>.
%% TODO: call your mother

%% 使用 -type 代替
%% @type

Notes on XHTML

EDoc标签中允许使用XHTML语法(特别是在@doc标签中)，与HTML语法主要有3点区别：
所有XHTML必须由明确的开始和结束标签，并且要正确嵌套
XHTML标签和属性名称始终是小写
Attributes must be quoted, as in e.g. <a name="top">.

Wiki notation

当EDoc解析XHTML时，会对文本进行额外的处理，以便将EDoc的某些特定的符号扩展为适当的XHTML标记

段落

在XHTML文本中留下空行(即任何以注释%符号开头且只包含空格的行)，EDoc会将空行前和空行后文本拆分为单独的段落

1
2
3
4
5
6
%% @doc 这是第一段，它可以
%% 跨多行并包含<em>任何XHTML
%% 标记</em>
%% 
%% 这是第二段，上面的行被EDoc
%% 视为空行，它的结尾有一个空格

拆分段落实际上是在XHTML解析之后发生的，它只会影响块级文本，而不会影响<pre>标记内或者<p>标记内的文本

标题

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
== 标题 ==
=== 二级标题 ===
==== 三级标题 ====
%% 标题只能存在于一行(不能跨行)

%% 一个名字叫 Sub heading 的标签
=== Sub-heading ===

%% 一个名字叫 Sub heading 的标签 且可跳转至 Sub_heading
=== Sub heading ===
%% 等同于
<h3><a name="Sub_heading">Sub heading</a><h3>

%% 使用宏创建超链接 这个动作发生在XML解析之前
{@section Sub heading}
%% 等同于
<a href="#Sub_heading">Sub heading</a>

外部链接

1
2
3
[http://www.w3c.org/]
%% 等同于
<a href="http://www.w3c.org/"><tt>http://www.w3c.org/</tt></a>

可以识别http/ftp/file协议
这个动作同样发生于XML解析之前

TODO

1
2
3
%% @TODO Finish writing the documentation.
%% @todo Implement <a href="http://www.ietf.org/rfc/rfc2549.txt">RFC 2549</a>.
%% TODO: call your mother

反引号`

反引号开头，单引号结尾
`xx'等同于<code>xx</code>，其中出现的特殊字符会被转义成对应的HTML编码，e.g.< &lt;
开头和结尾的空格会被删去。

两个反引号开头，两个单引号结尾
``xx''用于包含内部有一个单引号'的文本，e.g.``%% @doc' ''
如果内部包含多个'，可以显式使用<code></code>

三个反引号开头，三个单引号结尾
```xxx'''等同于<pre><![CDATA[xx]]></pre>，这会禁用文本中所有的XML消极，以固定字体显示，并保留缩进
结尾的空格会被删去

要显示一个单独的`可以用HTML编码&#96;

Macro expansion

规则

使用宏扩展有两种形式 {@name} {@name argument}
其中名称和参数之间必须要有一个或多个空格字符分隔
参数可以是任何文本，也可以包含其它宏扩展
没有转义的{@和}必须要成对出现

自定义宏

可以使用 def 定义宏
参考edoc:file/2和edoc:get_doc/2
自定义宏会覆盖预定义宏

预定义宏

Macro Desc
{@date} 当前系统日期 e.g.Dec 12 2016
{@link reference. description} 创建超链接 e.g.{@link edoc:file/2. <em>this link</em>}
{@module} 当前模块名
{@section heading} 链接到指定段落的超链接
{@time} 当前系统时间 e.g.21:53:19
{@type type-expression} 类型约束定义，使用-type代替
{@version} 版本 默认使用{@date}和{@time}
#### 转义
EDoc中使用@作为转义符 
1
2
3
4
5
6
%% 显示 {
@{
%% 显示 }
@}
%% 显示 @
@@
1
2
3
%% @doc You might want to write something like
%% @@foo that will expand to @foo and does not start
%% a new tag even if it appears first in a line.

类型及函数约束规范

EDoc中的类型约束@type @spec可以使用-type -spec代替，优势在于可以使用Dialyzer代码静态类型分析工具，Erlang类型及函数约束规范-More。