View Source shell_docs (stdlib v6.0)

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

Render module or function documentation.

Render the documentation for a function.

Render all callbacks in a module or callback documentation.

Render the documentation of a callback in a module.

Render all types in a module or 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

Link to this type

chunk_element()

View Source (not exported) (since OTP 23.0)
-type chunk_element() :: {chunk_element_type(), chunk_element_attrs(), chunk_elements()} | binary().
Link to this type

chunk_element_attr()

View Source (since OTP 23.0)
-type chunk_element_attr() :: {atom(), unicode:chardata()}.
Link to this type

chunk_element_attrs()

View Source (not exported) (since OTP 23.0)
-type chunk_element_attrs() :: [chunk_element_attr()].
Link to this type

chunk_element_block_type()

View Source (not exported) (since OTP 23.0)
-type chunk_element_block_type() ::
    p | 'div' | br | pre | ul | ol | li | dl | dt | dd | h1 | h2 | h3 | h4 | h5 | h6.
Link to this type

chunk_element_inline_type()

View Source (not exported) (since OTP 23.0)
-type chunk_element_inline_type() :: a | code | em | strong | i | b.
Link to this type

chunk_element_type()

View Source (not exported) (since OTP 23.0)
-type chunk_element_type() :: chunk_element_inline_type() | chunk_element_block_type().

The HTML tags allowed in application/erlang+html.

Link to this type

chunk_elements()

View Source (since OTP 23.0)
-type chunk_elements() :: [chunk_element()].
Link to this type

config()

View Source (not exported) (since OTP 23.2)
-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_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().

Link to this type

docs_v1()

View Source (not exported) (since OTP 23.0)
-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

Link to this function

normalize(Docs)

View Source (since OTP 23.0)
-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.

Link to this function

render(Module, Docs)

View Source (since OTP 23.0)
-spec render(Module, Docs) -> unicode:chardata() when Module :: module(), Docs :: docs_v1().

Equivalent to render(Module, Docs, #{}).

Link to this function

render(Module, DocsOrFunction, ConfigOrDocs)

View Source (since OTP 23.0)
-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).

Link to this function

render(Module, Function, DocsOrArity, ConfigOrDocs)

View Source (since OTP 23.0)
-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).

Link to this function

render(Module, Function, Arity, Docs, Config)

View Source (since OTP 23.0)
-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.

Link to this function

render_callback(Module, Docs)

View Source (since OTP 23.0)
-spec render_callback(Module, Docs) -> unicode:chardata() when Module :: module(), Docs :: docs_v1().

Equivalent to render_callback(Module, Docs, #{}).

Link to this function

render_callback(Module, DocsOrCallback, ConfigOrDocs)

View Source (since OTP 23.0)
-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).

Link to this function

render_callback(Module, Callback, DocsOrArity, ConfigOrDocs)

View Source (since OTP 23.0)
-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).

Link to this function

render_callback(Module, Callback, Arity, Docs, Config)

View Source (since OTP 23.0)
-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.

Link to this function

render_type(Module, Docs)

View Source (since OTP 23.0)
-spec render_type(Module, Docs) -> unicode:chardata() when Module :: module(), Docs :: docs_v1().

Equivalent to render_type(Module, Docs, #{}).

Link to this function

render_type(Module, DocsOrType, ConfigOrDocs)

View Source (since OTP 23.0)
-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).

Link to this function

render_type(Module, Type, DocsOrArity, ConfigOrDocs)

View Source (since OTP 23.0)
-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).

Link to this function

render_type(Module, Type, Arity, Docs, Config)

View Source (since OTP 23.0)
-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.

Link to this function

supported_tags()

View Source (since OTP 24.0)
-spec supported_tags() -> [chunk_element_type()].

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

Link to this function

validate(Module)

View Source (since OTP 23.0)
-spec 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.