edoc_extract — edoc v1.3.1

Search documentation of edoc

# View Source edoc_extract (edoc v1.3.1)

EDoc documentation extraction.

See also: edoc.

# Summary

## Types

context/0
filename/0
proplist/0

## Functions

file(File, Context, Env, Opts)

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'.

header(File, Env, Opts)

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

header(Forms, File, Env, Opts)

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.

header(Forms, Comments, File, Env, Opts)

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`.)

source(File, Env, Opts)

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

source(Forms, File, Env, Opts)

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.

source(Forms, Comments, File, Env, Opts)

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`.)

text(Text, Context, Env, Opts)

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`.

# Types

Link to this type

# context/0

View Source

    -type context() :: module | footer | function | overview | single.

Link to this type

# filename/0

View Source

    -type filename() :: file:filename().

Link to this type

# proplist/0

View Source

    -type proplist() :: proplists:proplist().

# Functions

Link to this function

# file(File, Context, Env, Opts)

View Source

    -spec 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 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.

Link to this function

# header(File, Env, Opts)

View Source

    -spec header(File, Env, Opts) -> edoc:entry_data()
                    when 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.

Link to this function

# header(Forms, File, Env, Opts)

View Source

    -spec 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 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: //syntax_tools/erl_recomment, header/5.

Link to this function

# header(Forms, Comments, File, Env, Opts)

View Source

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

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

Link to this function

# source(File, Env, Opts)

View Source

    -spec 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 reads the syntax tree and the comments from the specified file.

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

Link to this function

# source(Forms, File, Env, Opts)

View Source

    -spec 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 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: //syntax_tools/erl_recomment, source/5, edoc:read_comments/2, edoc:read_source/2.

Link to this function

# source(Forms, Comments, File, Env, Opts)

View Source

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

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

Link to this function

# text(Text, Context, Env, Opts)

View Source

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

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