shell_docs (stdlib v3.15.2)

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 docs 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 Erl_Docgen's User's Guide. It can also render any other format of "text" type, although those will be rendered as is.

Link to this section Summary

Types

-type chunk_element() :: term().

-type chunk_element_attr() :: term().

-type chunk_element_attrs() :: term().

-type chunk_element_block_type() :: term().

The HTML tags allowed in application/erlang+html.

-type chunk_element_inline_type() :: term().

The HTML tags allowed in application/erlang+html.

-type chunk_element_type() :: term().

The HTML tags allowed in application/erlang+html.

-type chunk_elements() :: term().

-type config() :: term().

The configuration of how the documentation should be rendered.

-type docs_v1() :: 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

normalize/1

This function can be used to do whitespace normalization of application/erlang+html documentation.

render/2

Render the documentation for a module or function.

render/3

render/4

render/5

render_callback/2

Render the documentation of a callback in a module.

render_callback/3

render_callback/4

render_callback/5

render_type/2

Render the documentation of a type in a module.

render_type/3

render_type/4

render_type/5

supported_tags/0

This function can be used to find out which tags are supported by application/erlang+html documentation.

validate/1

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

Link to this section Types

-type chunk_element() :: term().

Specs

chunk_element() :: {chunk_element_type(), chunk_element_attrs(), chunk_elements()} | binary().

-type chunk_element_attr() :: term().

Specs

chunk_element_attr() :: {atom(), unicode:chardata()}.

-type chunk_element_attrs() :: term().

Specs

chunk_element_attrs() :: [chunk_element_attr()].

-type chunk_element_block_type() :: term().

Specs

chunk_element_block_type() ::
    p | 'div' | br | pre | ul | ol | li | dl | dt | dd | h1 | h2 | h3 | h4 | h5 | h6.

The HTML tags allowed in application/erlang+html.

-type chunk_element_inline_type() :: term().

Specs

chunk_element_inline_type() :: a | code | em | strong | i | b.

The HTML tags allowed in application/erlang+html.

-type chunk_element_type() :: term().

Specs

chunk_element_type() :: chunk_element_inline_type() | chunk_element_block_type().

The HTML tags allowed in application/erlang+html.

-type chunk_elements() :: term().

Specs

chunk_elements() :: [chunk_element()].

-type config() :: term().

Specs

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() value.
columns: Configure how wide the target documentation should be rendered. By default shell_docs used the value returned by io:columns().

-type docs_v1() :: term().

Specs

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.

Link to this section Functions

normalize/1

(since OTP 23.0)

Specs

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/2

(since OTP 23.0,OTP 23.2)

Specs

render(Module, Docs) -> unicode:chardata() when Module :: module(), Docs :: docs_v1().

Render the documentation for a module or function.

render/3

(since OTP 23.0,OTP 23.2)

Specs

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/4

(since OTP 23.0,OTP 23.2)

Specs

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/5

(since OTP 23.0,OTP 23.2)

Specs

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_callback/2

(since OTP 23.0,OTP 23.2)

Specs

render_callback(Module, Docs) -> unicode:chardata() when Module :: module(), Docs :: docs_v1().

Render the documentation of a callback in a module.

render_callback/3

(since OTP 23.0,OTP 23.2)

Specs

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_callback/4

(since OTP 23.0,OTP 23.2)

Specs

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/5

(since OTP 23.0,OTP 23.2)

Specs

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_type/2

(since OTP 23.0,OTP 23.2)

Specs

render_type(Module, Docs) -> unicode:chardata() when Module :: module(), Docs :: docs_v1().

Render the documentation of a type in a module.

render_type/3

(since OTP 23.0,OTP 23.2)

Specs

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_type/4

(since OTP 23.0,OTP 23.2)

Specs

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/5

(since OTP 23.0,OTP 23.2)

Specs

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

supported_tags/0

(since OTP 24.0)

Specs

supported_tags() -> [chunk_element_type()].

This function can be used to find out which tags are supported by application/erlang+html documentation.

validate/1

(since OTP 23.0)

Specs

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.