lib/erl_docgen/doc/src/doc_storage.xml


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

<?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>Documentation Storage</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><url href="https://www.erlang.org/erlang-enhancement-proposals/eep-0048.html">EEP-48</url>
      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>&lt;name&gt;</c> tags must be parseable to figure out the arity of the function.</item>
      <item>It is not allowed to mix <c>&lt;name&gt;</c> tags with #PCDATA and attributes.</item>
      <item>All <c>&lt;name&gt;</c> tags within <c>&lt;func&gt;</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 generic storage</p>
  </section>

  <section>
    <title>See Also</title>
    <p>
      <seealso marker="stdlib:shell_docs"><c>shell_docs(3)</c></seealso>,
      <seealso marker="kernel:code#get_doc-1"><c>code:get_doc(3)</c></seealso>
    </p>
  </section>

</chapter>