shell_docs(3)

NAME
shell_docs - Functions used to render EEP-48 style documentation for a shell.

DESCRIPTION

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 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.

DATA TYPES

chunk_element() :: {chunk_element_type(), chunk_element_attrs(), chunk_elements()} | binary().
chunk_element_attr() :: {atom(), unicode:chardata()}.
chunk_element_attrs() :: [chunk_element_attr()].
chunk_element_block_type() :: p | 'div' | blockquote | br | pre | ul | ol | li | dl | dt | dd | h1 | h2 | h3 | h4 | h5 | h6.
chunk_element_inline_type() :: a | code | em | strong | i | b.
chunk_element_type() :: chunk_element_inline_type() | chunk_element_block_type().

    The HTML tags allowed in application/erlang+html.
chunk_elements() :: [chunk_element()].
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_docs uses the value returned by io:getopts().
    ansi
        Configure whether ansi escape codes should be used to render graphical details such as bold and underscore. By default shell_docs will try to determine if the receiving shell supports ansi escape codes. It is possible to override the automated check by setting the kernel configuration parameter shell_docs_ansi to a boolean/0 value.
    columns
        Configure how wide the target documentation should be rendered. By default shell_docs used the value returned by io:columns(). It is possible to override this default by setting the stdlib configuration parameter shell_docs_columns to a pos_integer/0 value.
docs_v1() :: #docs_v1{}.

    The record holding EEP-48 documentation for a module. You can use code:get_doc/1 to fetch this information from a module.

FUNCTIONS

normalize(Docs) -> NormalizedDocs when Docs :: chunk_elements(), NormalizedDocs :: chunk_elements().

    This function can be used to do whitespace normalization of application/erlang+html documentation.
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).
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).
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.
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).
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).
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.
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).
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).
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.
supported_tags() -> [chunk_element_type()].

    This function can be used to find out which tags are supported by application/erlang+html documentation.
validate(Module) -> ok when Module :: module() | docs_v1().

    This function can be used to do a basic validation of the doc content of application/erlang+html format.