shell_docs(3)
💅 NAME 💅
shell_docs — Functions used to render EEP-48 style documentation for a shell. 🫶
🌈 DESCRIPTION 🌈
okay so literally, this module is the one that makes function and type documentation look cute when it gets printed in a shell. ✨ It's the module that renders the docs you pull up in the shell through h/1,2,3. Example time, bestie:
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. Want the deets on that format? Go read Documentation Storage in EDoc's User's Guide, it's giving required reading. 📚 It can also render any other format of "text" type, although those will be rendered as is. no fancy formatting, just vibes.
🎀 DATA TYPES 🎀
chunk_element() 🌸
chunk_element() ::
{chunk_element_type(),
chunk_element_attrs(),
chunk_elements()} |
binary().chunk_element_attr() ⭐
chunk_element_attr() :: {atom(), unicode:chardata()}.chunk_element_attrs() 💜
chunk_element_attrs() :: [chunk_element_attr()].chunk_element_block_type() 🦋
chunk_element_block_type() ::
p | 'div' | blockquote | 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. that's the whole guest list, no plus-ones. 🙈
chunk_elements() 🧚
chunk_elements() :: [chunk_element()].config() 👑
config() ::
#{encoding => unicode | latin1,
columns => pos_integer(),
ansi => boolean()}.The configuration of how the documentation should be rendered. the whole aesthetic, basically. 💅
encoding— Configure the encoding that should be used by the renderer for graphical details such as bullet-points. By defaultshell_docsuses the value returned byio:getopts().ansi— Configure whether ansi escape codes should be used to render graphical details such as bold and underscore. By defaultshell_docswill try to determine if the receiving shell supports ansi escape codes. It is possible to override the automated check by setting the kernel configuration parametershell_docs_ansito aboolean/0value.columns— Configure how wide the target documentation should be rendered. By defaultshell_docsused the value returned byio:columns(). It is possible to override this default by setting the stdlib configuration parametershell_docs_columnsto apos_integer/0value.
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. fetch, like, it's right there bestie. 😌
🔥 FUNCTIONS 🔥
normalize/1 ✨
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,3 🫶
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/3,4 🌸
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/5 ⭐
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. that's it, that's the tweet. 🐦
render_callback/2,3 🦋
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/3,4 💜
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/5 🧚
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. iconic behaviour, honestly. 👑
render_type/2,3 🌈
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/3,4 💅
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/5 🌸
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/0 ⭐
supported_tags() -> [chunk_element_type()].This function can be used to find out which tags are supported by application/erlang+html documentation. a little vibe check for your tags. 🔍
validate/1 🔥
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. basic, not thorough — it said basic, bestie, so don't come for it. 🙈
k that's the whole page 💖 every flag, every clause, every {error, ...} tuple, all of it. no cap.
later bestie!! this lil masterpiece was brought to you by Ericsson AB, running stdlib 8.0.4, and yes it's shell_docs(3) and it ate. periodt. 💅✨🎀
📦 where this page comes from
- ubuntu stonking: erlang-doc 1:29.0.6+dfsg-1 · Apache-2.0
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms