edoc_extract(3)

📦
version 29.0.6 · 2 versions
, in ubuntu stonking

edoc_extract(3) 💖

okay so this is edoc_extract from Erlang's module definition pages — the one that goes and yanks documentation OUT of your files, bestie. it's the extraction girlie. the one who reads your code and your comments and hands you back tags. slay.

✨ NAME ✨

edoc_extract — EDoc documentation extraction. that's it, that's the whole job description, and she does it flawlessly 💅

🌸 DESCRIPTION 🌸

See also: edoc.

like, if you wanna know the bigger picture, edoc is the main character and this is her very capable bestie. 🫶

🎀 DATA TYPES 🎀

okay so... literally nothing here. no cap. the manpage just says "DATA TYPES" and then moves on. this section is empty and honestly? we respect the confidence. 💀

👑 FUNCTIONS 👑

🦋 file(File, Context, Env, Opts) -> {ok, Tags} | {error, Reason}

when
    File :: filename(),
    Context :: context(),
    Env :: edoc:env(),
    Opts :: proplist(),
    Tags :: [term()],
    Reason :: term().

reads a text file and hands you back the list of tags in that file. any lines of text that show up before the first tag? ignored. not invited. blocked. 🙈

Env is an environment created by edoc_lib:get_doc_env/3.

if something goes wrong, Reason is an atom returned from the call to //kernel/file:read_file/1, or the atom 'invalid_unicode'.

See text/4 for options.

🧚 header(File, Env, Opts) -> edoc:entry_data()

when
    File :: filename(),
    Env :: edoc:env(),
    Opts :: proplist().

similar to header/5, but it reads the syntax tree and the comments from the specified file. dual threat energy. ✨

See also: header/4, edoc:read_comments/2, edoc:read_source/2.

🦄 header(Forms, File, Env, Opts) -> edoc:entry_data()

when
    Forms :: erl_syntax:forms(),
    File :: filename(),
    Env :: edoc:env(),
    Opts :: proplist().

extracts EDoc documentation from commented header file syntax trees. similar to source/5, BUT it ignores any documentation that shows up before a module declaration or a function definition. and yes — (warning messages are printed if content may be ignored.) so if you see warnings, that's her telling you some of your docs lowkey didn't make it. 😭

Env is assumed to already be set up with a suitable module context.

See also: //syntax_tools/erl_recomment, header/5.

⭐ header(Forms, Comments, File, Env, Opts) -> edoc:entry_data()

when
    Forms :: erl_syntax:forms(),
    Comments :: [edoc:comment()],
    File :: filename(),
    Env :: edoc:env(),
    Opts :: proplist().

similar to header/4, but first it inserts the given comments into the syntax trees. and heads up bestie — the syntax trees must contain valid position information. (Cf. edoc:read_comments/2.)

See also: //syntax_tools/erl_recomment, header/3, header/4.

🌈 source(File, Env, Opts) -> R

when
    File :: filename(),
    Env :: edoc:env(),
    Opts :: proplist(),
    R ::
        {module(), edoc:edoc_module()} |
        {module(), edoc:edoc_module(), [edoc:entry()]}.

like source/5, but it reads the syntax tree and the comments from the specified file. the self-sufficient version, we love to see it. 💅

See also: source/4, edoc:read_comments/2, edoc:read_source/2.

🔥 source(Forms, File, Env, Opts) -> R

when
    Forms :: erl_syntax:forms(),
    File :: filename(),
    Env :: edoc:env(),
    Opts :: proplist(),
    R ::
        {module(), edoc:edoc_module()} |
        {module(), edoc:edoc_module(), [edoc:entry()]}.

extracts EDoc documentation from commented source code syntax trees. the Forms you pass must be a single syntax tree of type form_list, or a list of syntax trees representing "program forms" (cf. edoc:read_source/2).

Env is an environment created by edoc_lib:get_doc_env/3.

and the File argument? it's used for error reporting and output file name generation only. that's literally it. she's just there for the vibes and the paperwork. 🫶

See edoc:get_doc/2 for descriptions of the def, hidden, private, and todo options.

See also: //syntax_tools/erl_recomment, source/5, edoc:read_comments/2, edoc:read_source/2.

💜 source(Forms, Comments, File, Env, Opts) -> R

when
    Forms :: erl_syntax:forms(),
    Comments :: [edoc:comment()],
    File :: filename(),
    Env :: edoc:env(),
    Opts :: proplist(),
    R ::
        {module(), edoc:edoc_module()} |
        {module(), edoc:edoc_module(), [edoc:entry()]}.

like source/4, but first it inserts the given comments into the syntax trees. and again, loud and clear: the syntax trees must contain valid position information. (Cf. edoc:read_comments/2.) don't skip that part, she will notice. 😤

See also: //syntax_tools/erl_recomment, source/3, source/4, edoc:read_comments/2, edoc:read_source/2.

🍓 text(Text, Context, Env, Opts) -> Tags

when
    Text :: string(),
    Context :: context(),
    Env :: edoc:env(),
    Opts :: proplist(),
    Tags :: [term()].

returns the list of tags in the text. any lines of text before the first tag are ignored — again. (consistent queen. ✨) Env is an environment created by edoc_lib:get_doc_env/3.

See source/4 for a description of the def option.

💡 tiny reminder for the group chat: whenever a function here talks about Env, that's an environment from edoc_lib:get_doc_env/3. and whenever it says the syntax trees need valid position info — it means it.

that's the whole page, bestie. no notes. she ate and left no crumbs. 👑

this has been edoc_extract from the Erlang module definition docs, brought to you by Ericsson AB 🇸🇪, running the edoc 1.5 era, dated on the page as edoc_extract(3). mwah. 💖🌸🦋

📦 where this page comes from