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

chunk_element()

chunk_element_attr()

chunk_element_attrs()

chunk_element_block_type()

chunk_element_inline_type()

chunk_element_type()

The HTML tags allowed in application/erlang+html.

chunk_elements()

config()

The configuration of how the documentation should be rendered.

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)

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

render(Module, Docs)

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

render(Module, DocsOrFunction, ConfigOrDocs)

Render module or function documentation.

render(Module, Function, DocsOrArity, ConfigOrDocs)

Render function documentation.

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

Render the documentation for a function.

render_callback(Module, Docs)

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

render_callback(Module, DocsOrCallback, ConfigOrDocs)

Render all callbacks in a module or callback documentation.

render_callback(Module, Callback, DocsOrArity, ConfigOrDocs)

Render callback documentation.

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

Render the documentation of a callback in a module.

render_type(Module, Docs)

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

render_type(Module, DocsOrType, ConfigOrDocs)

Render all types in a module or type documentation.

render_type(Module, Type, DocsOrArity, ConfigOrDocs)

Render type documentation.

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

Render the documentation of a type in a module.

supported_tags()

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

validate(Module)

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

Types

chunk_element()

(not exported) (since OTP 23.0)

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

chunk_element_attr()

(since OTP 23.0)

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

chunk_element_attrs()

(not exported) (since OTP 23.0)

-type chunk_element_attrs() :: [chunk_element_attr()].

chunk_element_block_type()

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

chunk_element_inline_type()

(not exported) (since OTP 23.0)

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

chunk_element_type()

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

chunk_elements()

(since OTP 23.0)

-type chunk_elements() :: [chunk_element()].

config()

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

docs_v1()

(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

normalize(Docs)

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

render(Module, Docs)

(since OTP 23.0)

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

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

render(Module, DocsOrFunction, ConfigOrDocs)

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

render(Module, Function, DocsOrArity, ConfigOrDocs)

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

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

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

render_callback(Module, Docs)

(since OTP 23.0)

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

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

render_callback(Module, DocsOrCallback, ConfigOrDocs)

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

render_callback(Module, Callback, DocsOrArity, ConfigOrDocs)

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

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

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

render_type(Module, Docs)

(since OTP 23.0)

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

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

render_type(Module, DocsOrType, ConfigOrDocs)

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

render_type(Module, Type, DocsOrArity, ConfigOrDocs)

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

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

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

supported_tags()

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

validate(Module)

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