Erlang EDoc

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/2edoc: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