shell_docs (stdlib v7.0)
View SourceFunctions used to render EEP-48 style documentation for a shell.
This module can be used to render function and type documentation to be printed
in a shell. This is the module that is used to render the documentation accessed through
the shell through c:h/1,2,3). Example:
1> h(maps,new,0).
-spec new() -> Map when Map :: #{}.
Since:
OTP 17.0
Returns a new empty map.
Example:
> maps:new().
#{}This module formats and renders EEP-48 documentation of the format
application/erlang+html. For more information about this format see
Documentation Storage in EDoc's User's
Guide. It can also render any other format of "text" type, although those will
be rendered as is.
Summary
Types
The HTML tags allowed in application/erlang+html.
The configuration of how the documentation should be rendered.
The record holding EEP-48 documentation for a module. You can use
code:get_doc/1 to fetch this information from a module.
Functions
This function can be used to do whitespace normalization of
application/erlang+html documentation.
Equivalent to render(Module, Docs, #{}).
Render module or function documentation.
Render function documentation.
Render the documentation for a function.
Equivalent to render_callback(Module, Docs, #{}).
Render all callbacks in a module or callback documentation.
Render callback documentation.
Render the documentation of a callback in a module.
Equivalent to render_type(Module, Docs, #{}).
Render all types in a module or type documentation.
Render type documentation.
Render the documentation of a type in a module.
This function can be used to find out which tags are supported by
application/erlang+html documentation.
This function can be used to do a basic validation of the doc content of
application/erlang+html format.
Types
-type chunk_element() :: {chunk_element_type(), chunk_element_attrs(), chunk_elements()} | binary().
-type chunk_element_attr() :: {atom(), unicode:chardata()}.
-type chunk_element_attrs() :: [chunk_element_attr()].
-type chunk_element_block_type() ::
p | 'div' | blockquote | br | pre | ul | ol | li | dl | dt | dd | h1 | h2 | h3 | h4 | h5 | h6.
-type chunk_element_inline_type() :: a | code | em | strong | i | b.
-type chunk_element_type() :: chunk_element_inline_type() | chunk_element_block_type().
The HTML tags allowed in application/erlang+html.
-type chunk_elements() :: [chunk_element()].
-type config() :: #{encoding => unicode | latin1, columns => pos_integer(), ansi => boolean()}.
The configuration of how the documentation should be rendered.
encoding - Configure the encoding that should be used by the renderer for graphical details such as bullet-points. By default
shell_docsuses the value returned byio:getopts().ansi - Configure whether ansi escape codes should be used to render graphical details such as bold and underscore. By default
shell_docswill try to determine if the receiving shell supports ansi escape codes. It is possible to override the automated check by setting the kernel configuration parametershell_docs_ansito aboolean/0value.columns - Configure how wide the target documentation should be rendered. By default
shell_docsused the value returned byio:columns(). It is possible to override this default by setting the stdlib configuration parametershell_docs_columnsto apos_integer/0value.
-type docs_v1() :: #docs_v1{anno :: term(), beam_language :: term(), format :: term(), module_doc :: term(), metadata :: term(), docs :: term()}.
The record holding EEP-48 documentation for a module. You can use
code:get_doc/1 to fetch this information from a module.
Functions
-spec normalize(Docs) -> NormalizedDocs when Docs :: chunk_elements(), NormalizedDocs :: chunk_elements().
This function can be used to do whitespace normalization of
application/erlang+html documentation.
-spec render(Module, Docs) -> unicode:chardata() when Module :: module(), Docs :: docs_v1().
Equivalent to render(Module, Docs, #{}).
-spec render(Module, Docs, Config) -> unicode:chardata() when Module :: module(), Docs :: docs_v1(), Config :: config(); (Module, Function, Docs) -> Res when Module :: module(), Function :: atom(), Docs :: docs_v1(), Res :: unicode:chardata() | {error, function_missing}.
Render module or function documentation.
Renders the module documentation if called as render(Module, Docs, Config).
Equivalent to render(Module, Function, Docs, #{}) if called
as render(Module, Function, Docs).
-spec render(Module, Function, Docs, Config) -> Res when Module :: module(), Function :: atom(), Docs :: docs_v1(), Config :: config(), Res :: unicode:chardata() | {error, function_missing}; (Module, Function, Arity, Docs) -> Res when Module :: module(), Function :: atom(), Arity :: arity(), Docs :: docs_v1(), Res :: unicode:chardata() | {error, function_missing}.
Render function documentation.
Renders the function documentation if called as render(Module, Function, Docs, Config).
Equivalent to render(Module, Function, Arity, Docs, #{}) if called
as render(Module, Function, Arity, Docs).
-spec render(Module, Function, Arity, Docs, Config) -> Res when Module :: module(), Function :: atom(), Arity :: arity(), Docs :: docs_v1(), Config :: config(), Res :: unicode:chardata() | {error, function_missing}.
Render the documentation for a function.
-spec render_callback(Module, Docs) -> unicode:chardata() when Module :: module(), Docs :: docs_v1().
Equivalent to render_callback(Module, Docs, #{}).
-spec render_callback(Module, Docs, Config) -> unicode:chardata() when Module :: module(), Docs :: docs_v1(), Config :: config(); (Module, Callback, Docs) -> Res when Module :: module(), Callback :: atom(), Docs :: docs_v1(), Res :: unicode:chardata() | {error, callback_missing}.
Render all callbacks in a module or callback documentation.
Renders a list with all callbacks if called as render_callback(Module, Docs, Config).
Equivalent to render_callback(Module, Callback, Docs, #{}) if called
as render_callback(Module, Callback, Docs).
-spec render_callback(Module, Callback, Docs, Config) -> Res when Module :: module(), Callback :: atom(), Docs :: docs_v1(), Config :: config(), Res :: unicode:chardata() | {error, callback_missing}; (Module, Callback, Arity, Docs) -> Res when Module :: module(), Callback :: atom(), Arity :: arity(), Docs :: docs_v1(), Res :: unicode:chardata() | {error, callback_missing}.
Render callback documentation.
Renders the callback documentation if called as render_callback(Module, Callback, Docs, Config).
Equivalent to render_callback(Module, Callback, Arity, Docs, #{}) if called
as render_callback(Module, Callback, Arity, Docs).
-spec render_callback(Module, Callback, Arity, Docs, Config) -> Res when Module :: module(), Callback :: atom(), Arity :: arity(), Docs :: docs_v1(), Config :: config(), Res :: unicode:chardata() | {error, callback_missing}.
Render the documentation of a callback in a module.
-spec render_type(Module, Docs) -> unicode:chardata() when Module :: module(), Docs :: docs_v1().
Equivalent to render_type(Module, Docs, #{}).
-spec render_type(Module, Docs, Config) -> unicode:chardata() when Module :: module(), Docs :: docs_v1(), Config :: config(); (Module, Type, Docs) -> Res when Module :: module(), Type :: atom(), Docs :: docs_v1(), Res :: unicode:chardata() | {error, type_missing}.
Render all types in a module or type documentation.
Renders a list with all types if called as render_type(Module, Docs, Config).
Equivalent to render_type(Module, Type, Docs, #{}) if called
as render_type(Module, Type, Docs).
-spec render_type(Module, Type, Docs, Config) -> Res when Module :: module(), Type :: atom(), Docs :: docs_v1(), Config :: config(), Res :: unicode:chardata() | {error, type_missing}; (Module, Type, Arity, Docs) -> Res when Module :: module(), Type :: atom(), Arity :: arity(), Docs :: docs_v1(), Res :: unicode:chardata() | {error, type_missing}.
Render type documentation.
Renders the type documentation if called as render_type(Module, Type, Docs, Config).
Equivalent to render_type(Module, Type, Arity, Docs, #{}) if called
as render_type(Module, Type, Arity, Docs).
-spec render_type(Module, Type, Arity, Docs, Config) -> Res when Module :: module(), Type :: atom(), Arity :: arity(), Docs :: docs_v1(), Config :: config(), Res :: unicode:chardata() | {error, type_missing}.
Render the documentation of a type in a module.
-spec supported_tags() -> [chunk_element_type()].
This function can be used to find out which tags are supported by
application/erlang+html documentation.
This function can be used to do a basic validation of the doc content of
application/erlang+html format.