1shell_docs(3)              Erlang Module Definition              shell_docs(3)
2
3
4

NAME

6       shell_docs  - Functions used to render EEP-48 style documentation for a
7       shell.
8

DESCRIPTION

10       This module can be used to render function and type documentation to be
11       printed  in a shell. This is the module that is used to render the docs
12       accessed through the shell through c:h/1,2,3. Example:
13
14       1> h(maps,new,0).
15
16         -spec new() -> Map when Map :: #{}.
17
18       Since:
19         OTP 17.0
20
21         Returns a new empty map.
22
23         Example:
24
25           > maps:new().
26           #{}
27
28
29       This module formats and renders EEP-48 documentation of the format  ap‐
30       plication/erlang+html. For more information about this format see Docu‐
31       mentation Storage in Erl_Docgen's User's Guide. It can also render  any
32       other format of "text" type, although those will be rendered as is.
33

DATA TYPES

35       docs_v1() = #docs_v1{}
36
37              The  record  holding  EEP-48 documentation for a module. You can
38              use code:get_doc/1 to fetch this information from a module.
39
40       config() =
41           #{encoding => unicode | latin1,
42             columns => integer() >= 1,
43             ansi => boolean()}
44
45              The configuration of how the documentation should be rendered.
46
47                encoding:
48                   Configure the encoding that should be used by the  renderer
49                  for  graphical  details  such  as  bullet-points. By default
50                  shell_docs uses the value returned by io:getopts().
51
52                ansi:
53                   Configure whether  ansi escape codes should be used to ren‐
54                  der  graphical  details  such as bold and underscore. By de‐
55                  fault shell_docs will try  to  determine  if  the  receiving
56                  shell supports ansi escape codes. It is possible to override
57                  the automated check by setting the kernel configuration  pa‐
58                  rameter shell_docs_ansi to a boolean() value.
59
60                columns:
61                   Configure  how wide the target documentation should be ren‐
62                  dered. By default shell_docs  used  the  value  returned  by
63                  io:columns().
64
65       chunk_element_block_type() =
66           p | 'div' | br | pre | ul | ol | li | dl | dt | dd | h1 | h2 |
67           h3 | h4 | h5 | h6
68
69       chunk_element_inline_type() = a | code | em | strong | i | b
70
71       chunk_element_type() =
72           chunk_element_inline_type() | chunk_element_block_type()
73
74              The HTML tags allowed in application/erlang+html.
75
76       chunk_element_attr() = {atom(), unicode:chardata()}
77
78       chunk_element_attrs() = [chunk_element_attr()]
79
80       chunk_element() =
81           {chunk_element_type(),
82            chunk_element_attrs(),
83            chunk_elements()} |
84           binary()
85
86       chunk_elements() = [chunk_element()]
87

EXPORTS

89       render(Module, Docs) -> unicode:chardata()
90
91       render(Module, Docs, Config) -> unicode:chardata()
92
93       render(Module, Function, Docs) -> Res
94
95       render(Module, Function, Docs, Config) -> Res
96
97       render(Module, Function, Arity, Docs) -> Res
98
99       render(Module, Function, Arity, Docs, Config) -> Res
100
101              Types:
102
103                 Module = module()
104                 Function = atom()
105                 Arity = arity()
106                 Docs = docs_v1()
107                 Config = config()
108                 Res = unicode:chardata() | {error, function_missing}
109
110              Render the documentation for a module or function.
111
112       render_type(Module, Docs) -> unicode:chardata()
113
114       render_type(Module, Docs, Config) -> unicode:chardata()
115
116       render_type(Module, Type, Docs) -> Res
117
118       render_type(Module, Type, Docs, Config) -> Res
119
120       render_type(Module, Type, Arity, Docs) -> Res
121
122       render_type(Module, Type, Arity, Docs, Config) -> Res
123
124              Types:
125
126                 Module = module()
127                 Type = atom()
128                 Arity = arity()
129                 Docs = docs_v1()
130                 Config = config()
131                 Res = unicode:chardata() | {error, type_missing}
132
133              Render the documentation of a type in a module.
134
135       render_callback(Module, Docs) -> unicode:chardata()
136
137       render_callback(Module, Docs, Config) -> unicode:chardata()
138
139       render_callback(Module, Callback, Docs) -> Res
140
141       render_callback(Module, Callback, Docs, Config) -> Res
142
143       render_callback(Module, Callback, Arity, Docs) -> Res
144
145       render_callback(Module, Callback, Arity, Docs, Config) -> Res
146
147              Types:
148
149                 Module = module()
150                 Callback = atom()
151                 Arity = arity()
152                 Docs = docs_v1()
153                 Config = config()
154                 Res = unicode:chardata() | {error, callback_missing}
155
156              Render the documentation of a callback in a module.
157
158       validate(Module) -> ok
159
160              Types:
161
162                 Module = module() | docs_v1()
163
164              This  function  can  be used to do a basic validation of the doc
165              content of application/erlang+html format.
166
167       normalize(Docs) -> NormalizedDocs
168
169              Types:
170
171                 Docs = NormalizedDocs = chunk_elements()
172
173              This function can be used to do whitespace normalization of  ap‐
174              plication/erlang+html documentation.
175
176       supported_tags() -> [chunk_element_type()]
177
178              This  function  can be used to find out which tags are supported
179              by application/erlang+html documentation.
180
181
182
183Ericsson AB                       stdlib 4.2                     shell_docs(3)