shell_docs(3erl)

💖 NAME 💖

shell_docs — Functions used to render EEP-48 style documentation for a shell. This is the Erlang module definition, aka the iconic shell_docs(3erl) page, and it’s literally the glow-up zone for docs you wanna show off in the shell. 💅

✨ DESCRIPTION ✨

Okay bestie, so this module can be used to render function and type documentation to be printed in a shell. It’s 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.

Heads-up: other text formats get zero styling magic — they’re rendered as is, no cap. 🙈

---

🧁 DATA TYPES 🧁

docs_v1()

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. Obsessed with a convenient doc record? Same.

config()

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 uses the value returned by io:columns().

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

chunk_element_inline_type() = a | code | em | strong | i | b

chunk_element_type()

chunk_element_type() =
    chunk_element_inline_type() | chunk_element_block_type()

The HTML tags allowed in application/erlang+html.

chunk_element_attr()

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

chunk_element_attrs()

chunk_element_attrs() = [chunk_element_attr()]

chunk_element()

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

chunk_elements()

chunk_elements() = [chunk_element()]

---

🚀 EXPORTS 🚀

render — main character energy 👑

• 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 — type docs, but make it cute 🎀

• 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 — callback docs, slay 💅

• 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 — vibe check ✅

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 — whitespace cleanup ✨

Types:

Docs = NormalizedDocs = chunk_elements()

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

supported_tags() -> [chunk_element_type()] — tag inventory 🏷️

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

---

Final sign-off: source = Ericsson AB, version = stdlib 4.3.1.3, and the footer date/manual-label spot is the iconic shell_docs(3erl). That’s the whole vibe, bestie — now go render some gorgeous docs 💖✨