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
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
<year>1997</year><year>2016</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
</legalnotice>
<title>EEP-48: Implementation in Erlang/OTP</title>
<prepared></prepared>
<docno></docno>
<date></date>
<rev></rev>
<file>doc_storage.xml</file>
</header>
<section>
<title>EEP-48: Documentation storage and format</title>
<p><seeguide marker="kernel:eep48_chapter">EEP-48</seeguide>
defines a common documentation storage format for module documentation in the Erlang/OTP
ecosystem. Erl_Docgen can generate documentation in this format from XML files following
the DTD's descibed in the other User's Guides in this application.</p>
<p>Some special considerations have to be taken when writing documentation that
should also be available through EEP-48 style storage.</p>
<list>
<item>The <c>#PCDATA</c> within <c><name></c> tags must be parseable
to figure out the arity of the function.</item>
<item>It is not allowed to mix <c><name></c> tags with #PCDATA and attributes.</item>
<item>All <c><name></c> tags within <c><func></c>
has to have a <c>since</c> attribute.</item>
<item>All callback function documentations have to start with a <c>Module</c> prefix.</item>
</list>
</section>
<section>
<title>Erlang Documentation Format</title>
<p>When generating documentation for EEP-48 Erl_Docgen uses the format mime type
<<"application/erlang+html">>. The documentation content is an Erlang
term that represents an HTML like structure.</p>
<code>
-type chunk_elements() :: [chunk_element()].
-type chunk_element() :: {chunk_element_type(),chunk_element_attrs(),
chunk_elements()} | unicode:unicode_binary().
-type chunk_element_attrs() :: [chunk_element_attr()].
-type chunk_element_attr() :: {atom(),unicode:unicode_binary()}.
-type chunk_element_type() :: chunk_element_inline_type() | chunk_element_block_type().
-type chunk_element_inline_type() :: a | code | strong | b | em | i.
-type chunk_element_block_type() :: p | 'div' | br | pre | ul |
ol | li | dl | dt | dd |
h1 | h2 | h3 | h4 | h5 | h6.
</code>
<p>The different element types follow their HTML meaning when rendered.
The following are some general rules for how the chunk elements are allowed
to be generated.</p>
<list>
<item>Inline and <c>pre</c> elements are not allowed to contain block elements.</item>
<item><c>p</c> elements are not allowed to be nested.</item>
</list>
<p>The attributes on some elements have a special meaning.</p>
<taglist>
<tag><c>{'div',[{class,unicode:unicode_binary()}],_}</c></tag>
<item>The class name will be used to provide styling to the content in the div.
The types of classes used by Erlang/OTP are: <c>warning</c>, <c>note</c>, <c>do</c>,
<c>dont</c> and <c>quote</c>.</item>
<tag><c><![CDATA[{ul,[{class,<<"types">>}],_}]]></c></tag>
<item>This is a list containing type documentation.</item>
<tag><c><![CDATA[{li,[{name,TypeName :: unicode:unicode_binary()}],_}]]></c></tag>
<item>A list item with a type specification located in the metadata of this modules
EEP-48 documentation. The implementation should look for the AST representation of
the type under the <c>types</c> key. This attribute is only valid under a <c>ul</c>
with class <<"types">>.</item>
<tag><c><![CDATA[{li,[{class,<<"type">>}],_}]]></c></tag>
<item>A list item with the type described in the Erlang Documentation Format.
This attribute is only valid under a <c>ul</c> with class <<"types">>.</item>
<tag><c><![CDATA[{li,[{class,<<"description">>}],_}]]></c></tag>
<item>A list item with the description of the type previous in the list.
This attribute is only valid under a <c>ul</c> with class <<"types">>.</item>
</taglist>
<p>The <seemfa marker="stdlib:shell_docs#validate/1"><c>shell_docs:validate/1</c></seemfa>
function can be used to do a validation of the Erlang Documentation Format.</p>
</section>
<section>
<title>Erlang Documentation extra Metadata</title>
<p>Erlang/OTP uses some extra metadata fields to embed more information into the EEP-48 docs.</p>
<list>
<item>Fields on module level:
<taglist>
<tag><c>otp_doc_vsn := {non_neg_integer(),non_neg_integer(),non_neg_integer()}</c></tag>
<item>Describes the version of the Erlang Documentation Format used
within this module</item>
<tag><c>types := #{ TypeName :: unicode:unicode_binary() => TypeAST }</c></tag>
<item>A map containing the AST of the types that are part of this module.
This map is used to by functions and callbacks to render the types inline
into their documentation.</item>
</taglist>
</item>
<item>Fields on functions and types:
<taglist>
<tag><c>signature := SpecAST</c></tag>
<item>The spec AST associated with this function. It is used to render a more
descriptive slogan for the documentation entry.</item>
<tag><c>equiv := {Type,Name,Arity}</c></tag>
<item>The current function/type shares documentation with another function/type.
This means that if this and the target function/type are to be shown at the
same time only the prototype of this function/type should will be displayed
and the documentation will use a common body of text.</item>
</taglist>
</item>
</list>
</section>
<section>
<title>See Also</title>
<p>
<seeguide marker="kernel:eep48_chapter"></seeguide>
<seeerl marker="stdlib:shell_docs"><c>shell_docs(3)</c></seeerl>,
<seemfa marker="kernel:code#get_doc/1"><c>code:get_doc(3)</c></seemfa>
</p>
</section>
</chapter>
|
