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

DATA TYPES

       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.

       config() =
           #{encoding => unicode | latin1,
             columns => integer() >= 1,
             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().

       chunk_element_block_type() =
           p | 'div' | 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_element_attr() = {atom(), unicode:chardata()}

       chunk_element_attrs() = [chunk_element_attr()]

       chunk_element() =
           {chunk_element_type(),
            chunk_element_attrs(),
            chunk_elements()} |
           binary()

       chunk_elements() = [chunk_element()]

EXPORTS

       render(Module, Docs) -> unicode:chardata()

       render(Module, Docs, Config) -> unicode:chardata()

       render(Module, Function, Docs) -> Res

       render(Module, Function, Docs, Config) -> Res

       render(Module, Function, Arity, Docs) -> Res

       render(Module, Function, Arity, Docs, Config) -> Res

              Types:

                 Module = module()
                 Function = atom()
                 Arity = arity()
                 Docs = docs_v1()
                 Config = config()
                 Res = unicode:chardata() | {error, function_missing}

              Render the documentation for a module or function.

       render_type(Module, Docs) -> unicode:chardata()

       render_type(Module, Docs, Config) -> unicode:chardata()

       render_type(Module, Type, Docs) -> Res

       render_type(Module, Type, Docs, Config) -> Res

       render_type(Module, Type, Arity, Docs) -> Res

       render_type(Module, Type, Arity, Docs, Config) -> Res

              Types:

                 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.

       render_callback(Module, Docs) -> unicode:chardata()

       render_callback(Module, Docs, Config) -> unicode:chardata()

       render_callback(Module, Callback, Docs) -> Res

       render_callback(Module, Callback, Docs, Config) -> Res

       render_callback(Module, Callback, Arity, Docs) -> Res

       render_callback(Module, Callback, Arity, Docs, Config) -> Res

              Types:

                 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.

       validate(Module) -> ok

              Types:

                 Module = module() | docs_v1()

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

       normalize(Docs) -> NormalizedDocs

              Types:

                 Docs = NormalizedDocs = chunk_elements()

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

       supported_tags() -> [chunk_element_type()]

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