edoc(3)

📦
version 29.0.6 · 2 versions
, in ubuntu stonking

💖 NAME 💖

edoc — bestie, it's EDoc, the Erlang program documentation generator. That's the whole vibe. 📝✨

✨ DESCRIPTION ✨

okay so this module is like. the main character of the whole EDoc situation — it's the front door, the user interface you actually talk to. Everything else is backstage. 🎀

If you wanna go deeper, the lore lives here:

  • 📘 EDoc User Manual
  • 🏃 Running EDoc

🦋 DATA TYPES 🦋

  • edoc_module() :: xmerl_scan:xmlElement().

This is the EDoc documentation data for one module, and it's expressed as an XML document in XMerL format, bestie. If you want the juicy details on what that actually looks like, go check edoc.dtd. 🔍

  • entry() ::
#entry{name :: function_name() | atom(),
       args :: [atom() | list()],
       line :: integer(),
       export :: boolean(),
       data :: entry_data()}.

These are the Module Entries — you get one per function, plus the module header and the module footer. Like little trading cards for each function. 🃏

  • env() :: #env{}.

The environment info EDoc needs so it can generate references and not wildly point at nothing. 🧭

  • module_meta() ::
#module{name :: [] | atom(),
        parameters :: none | [atom()],
        functions :: ordset(function_name()),
        exports :: ordset(function_name()),
        attributes :: ordset({atom(), term()}),
        records :: [{atom(), [{atom(), term()}]}],
        encoding :: epp:source_encoding(),
        file :: file:filename()}.

Module information. The receipts, basically. 🧾

  • tag() ::
#tag{name :: atom(),
     line :: integer(),
     origin :: comment | code,
     data :: term(),
     form :: undefined | erl_parse:abstract_form()}.

Generic tag information. Heads up though — #tag.form only actually has a value if #tag.origin is code. Like, if the #tag{} represents a real code fragment and not a doc comment tag. Don't get it twisted. 💅

🔥 FUNCTIONS 🔥

🌸 application(atom()) -> ok.

Literally just the same as application(Application, []). Nothing else going on here. 💁

🌸 application(App, Options) -> ok when App :: atom(), Options :: proplist().

Runs EDoc on an application that lives in its default app-directory. That's it, that's the whole job. If you want the full story, go read application/3. 📖

See also: application/1.

🌸 application(App, Dir, Options) -> ok when App :: atom(), Dir :: filename(), Options :: proplist().

Runs EDoc on an application that's hanging out in the directory you specify. It tries to set up good defaults for you automatically (so thoughtful, honestly 😭). And unless you say otherwise:

  • 🎯 The doc subdirectory gets used as the target directory — but only if it exists. If it doesn't, the application directory itself gets used instead.
  • 📂 The source code is assumed to live in the src subdirectory, again only if it exists — otherwise it's assumed to be right there in the application directory itself.
  • 🌈 The subpackages option gets turned on. Every source file it finds will be processed. All of them. No survivors.
  • 🧵 The include subdirectory gets automatically added to the include path. (This only matters if preprocessing is turned on, so don't stress.)

For the full deets — options included — go see run/2.

See also: application/2.

🌸 file(filename()) -> ok.

⚠️ Deprecated! Check file/2 for the details, bestie.

Equivalent to file(Name, []). 🙈

🌸 file(Name, Options) -> ok when Name :: filename(), Options :: proplist().

⚠️ Deprecated, fr fr! This is part of the old interface to EDoc and it's mainly being kept around for backwards compatibility. The preferred way to generate docs is through application/2 or files/2. Use those. Please. 🙏

What it does: reads a source code file and outputs formatted documentation to a corresponding file. Classic.

Options:

  • {dir, filename()} — tells it where the created file should go. (By default, the output gets written to the same directory as the source file. Cozy.)
  • {source_suffix, string()} — the suffix you expect the input file to have. The default is ".erl".
  • {file_suffix, string()} — the suffix for the file it creates. The default is ".html".

For even more options, go peep get_doc/2 and layout/2.

If you're running EDoc from a Makefile or something similar, check out edoc_run:file/1. 🛠️

See also: read/2.

🌸 files(Files, Options) -> ok when Files :: [filename()], Options :: proplist().

This is the same as run(Files, Options). It runs EDoc over a given set of source files. Full deets, options and all, live in run/2. 📚

🌸 get_doc(filename()) -> {module(), edoc_module()}.

Same energy as get_doc(File, []). ✨

🌸 get_doc(File, Options) -> R when File :: filename(), Options :: proplist(), R :: {module(), edoc_module()} | {module(), edoc_module(), [entry()]}.

Reads a source code file and pulls out the EDoc documentation data. 🧲

⚠️ Heads up: if you don't pass an environment parameter (that's get_doc/3, bestie), your hypertext links might come out wrong. Not wrong-wrong, but like. Not correct. Just so you know. 😬

Options:

  • {def, Macros}
    • Macros = Macro | [Macro]
    • Macro = {Name::atom(), Text::string() | MacroFun}
    • MacroFun = fun((MacroArgument::string(), Line :: integer(), edoc_lib:edoc_env()) -> (Text::string()))

This one lets you specify a set of user-defined EDoc macros. The text that gets substituted for macro calls is given as either a string() or a function(). If you go the function route, it gets called with the macro argument text, the current line number, and the current environment — and the fun is supposed to return a string(). See Macro expansion for the whole story. 🪄

  • {hidden, boolean()} — if it's true, documentation for hidden functions gets included too. Default is false.
  • {private, boolean()} — if it's true, documentation for private functions gets included too. Default is false.
  • {todo, boolean()} — if it's true, To-Do notes written with @todo or @TODO tags get included in the documentation. Default is false.

For further options, see read_source/2, read_comments/2 and edoc_lib:get_doc_env/3.

See also: get_doc/3, layout/2, read/2, run/2, edoc_extract:source/5.

🌸 get_doc(File, Env, Options) -> R when File :: filename(), Env :: env(), Options :: proplist(), R :: {module(), edoc_module()} | {module(), edoc_module(), [entry()]}.

Exactly like get_doc/2, but now you're handing it a specific environment parameter. 🫶 And Env here is an environment that was created by edoc_lib:get_doc_env/3. That's the one you want.

🌸 layout(edoc_module()) -> string().

Just layout(Doc, []). Same thing, fewer keystrokes. ⌨️

🌸 layout(Doc, Opts) -> term() when Doc :: edoc_module(), Opts :: proplist().

This one transforms EDoc module documentation data into text. And the default layout? It makes an HTML document. Of course it does. 💅

Options:

  • {layout, Module::atom()} — names a callback module to be used for formatting. That module has to export a function called module(Doc, Options). The default callback module is edoc_layout, and if you want layout-specific options you should go read edoc_layout:module/2. 🎨
See also: file/2, layout/1, read/2, run/2.

🌸 read(filename()) -> string().

You guessed it — read(File, []). 💖

🌸 read(File, Opts) -> string() when File :: filename(), Opts :: proplist().

Reads and processes a source file, then hands you back the resulting EDoc-text as a string. Options live in get_doc/2 and layout/2. 📄

See also: file/2.

🌸 read_comments(filename()) -> [comment()].

Yep, read_comments(File, []). 🌸

🌸 read_comments(File, Opts) -> [comment()] when File :: filename(), Opts :: proplist().

Pulls the comments out of an Erlang source code file. 🧺 If you want the deets on how comments are actually represented, go check the //syntax_tools/erl_comment_scan module. And rn? No options are available. Zero. None. That's the whole menu. 😌

🌸 read_source(filename()) -> [syntaxTree()].

Again — read_source(File, []). ✨

🌸 read_source(File, Opts) -> [syntaxTree()] when File :: filename(), Opts :: proplist().

Reads an Erlang source file and gives you back the list of "source code form" syntax trees. 🌳

Options:

  • {preprocess, boolean()}

If it's true, the source file gets read through the Erlang preprocessor (epp). Default is false. Also, no_preprocess is an alias for {preprocess, false}. 🪄

Normally you don't need preprocessing for EDoc to work — but if a file has definitions or uses of macros that are just. Too exotic. Then it will be impossible to read it without preprocessing. 😭

⚠️ Note: comments in included files will not be available to EDoc, even with this option turned on. Sorry bestie, that's just how it is.
  • {includes, Path::[string()]} — a list of directory names to search for include files, used when the preprocess option is turned on. It also gets used with the @headerfile tag. The default value is the empty list, and the directory of the source file is always automatically appended to the search path. No takebacks. 📁
  • {macros, [{atom(), term()}]} — a list of pre-defined Erlang preprocessor (epp) macro definitions, used if the preprocess option is on. Default is the empty list. 🧬
  • {report_missing_types, boolean()} — if it's true, warnings get issued for missing types. Default is false. And no_report_missing_types is an alias for {report_missing_types, false}. 📢
  • {link_predefined_types, boolean()} — if it's true, all predefined data types get a link to the erlang module. This one is meant to be used when generating documentation for the Erlang/OTP docs. Default is false. And no_link_predefined_types is an alias for {link_predefined_types, false}. 🔗

See also: //syntax_tools/erl_syntax, get_doc/2. 🦋

run(Files, Opts) -> ok

run(Files, Opts) -> ok
             when Files :: [filename()], Opts :: proplist().

Runs EDoc on a given set of source files. Note that the doclet plugin module has its own particular options; see the doclet option below. 👑

Also see layout/2 for layout-related options, and get_doc/2 for options related to reading source files. 💅

Options

  • {app_default, string()} — Specifies the default base URI for unknown applications. 🌈
  • {application, App::atom()} — Specifies that the generated documentation describes the application App. This mainly affects generated references. 🎀
  • {dir, filename()} — Specifies the target directory for the generated documentation. 📁
  • {doc_path, [string()]} — Specifies a list of file system paths pointing to directories that contain EDoc-generated documentation. All paths for applications in the code path are automatically added. ✨
  • {doclet, Module::atom()} — Specifies a callback module to be used for creating the documentation. The module must export a function run(Cmd, Ctxt). The default doclet module is edoc_doclet; see edoc_doclet:run/2 for doclet-specific options. 🧚
  • {file_suffix, string()} — Specifies the suffix used for output files. The default value is ".html". Note that this also affects generated references. 💖
  • {new, boolean()} — If the value is true, any existing edoc-info file in the target directory will be ignored and overwritten. The default value is false. 💀
  • {source_path, [filename()]} — Specifies a list of file system paths used to locate the source code for packages. 🍓
  • {source_suffix, string()} — Specifies the expected suffix of input files. The default value is ".erl". 🌸
  • {subpackages, boolean()} — If the value is true, all subpackages of specified packages will also be included in the documentation. The default value is false. no_subpackages is an alias for {subpackages, false}. Subpackage source files are found by recursively searching for source code files in subdirectories of the known source code root directories. (Also see the source_path option.) Directory names must begin with a lowercase letter and contain only alphanumeric characters and underscore, or they will be ignored. (For example, a subdirectory named test-files will not be searched.) 💅

See also: application/2, files/2. 🫶

And that's the whole run/2 situation, bestie. Shoutout to Ericsson AB for edoc 1.5 and the edoc(3) date hanging out in the footer—no cap, iconic. 💖✨

📦 where this page comes from