edoc_extract(3erl)

💖 edoc_extract — EDoc documentation extraction, but make it make sense 💖

okay so bestie, welcome to the edoc_extract(3erl) manual page. this is the Erlang module doc for pulling EDoc documentation out of files, syntax trees, comments, and text. it's giving parser-adjacent main character energy, and we're gonna get through every function together. 🫶

✨ NAME ✨

edoc_extract — EDoc documentation extraction. literally the whole name, no notes. 💅

🌸 DESCRIPTION 🌸

EDoc documentation extraction. that's the description, bestie — short, sweet, and iconic. 🎀

🦋 DATA TYPES 🦋

• context() = module | footer | function | overview | single
• filename() = file:filename()
• proplist() = proplists:proplist()

👑 EXPORTS 👑

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

Types:

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

Reads a text file and returns the list of tags in the file. Any lines of text before the first tag are ignored. Env is an environment created by edoc_lib:get_doc_env/3. Upon error, Reason is an atom returned from the call to file:read_file/1 or the atom 'invalid_unicode'.

See text/4 for options. 💖

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

Types:

File = filename()
Env = edoc:env()
Opts = proplist()

Similar to header/5, but reads the syntax tree and the comments from the specified file.

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

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

Types:

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 ignores any documentation that occurs before a module declaration or a function definition. (Warning messages are printed if content may be ignored.) Env is assumed to already be set up with a suitable module context.

See also: erl_recomment(3erl), header/5. 🔥

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

Types:

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

Similar to header/4, but first inserts the given comments in the syntax trees. The syntax trees must contain valid position information. (Cf. edoc:read_comments/2.)

See also: erl_recomment(3erl), header/3, header/4. 🌈

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

Types:

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

Like source/5, but reads the syntax tree and the comments from the specified file.

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

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

Types:

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 given Forms 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. The File argument is used for error reporting and output file name generation only.

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

See also: erl_recomment(3erl), source/5, edoc:read_comments/2, edoc:read_source/2. 💜

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

Types:

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 inserts the given comments in the syntax trees. The syntax trees must contain valid position information. (Cf. edoc:read_comments/2.)

See also: erl_recomment(3erl), source/3, source/4, edoc:read_comments/2, edoc:read_source/2. 🎀

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

Types:

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. Env is an environment created by edoc_lib:get_doc_env/3.

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

🌟 SEE ALSO 🌟

edoc

🫶 AUTHORS 🫶

Richard Carlsson <carlsson.richard@gmail.com>

---

okay bestie, that's the whole page. footer sign-off: edoc 1.2, edoc_extract(3erl). stay slay, document your code, and may your tags always parse. 💖✨