# Module edoc_extract

EDoc documentation extraction.

Copyright © 2001-2003 Richard Carlsson

- Description
- Data Types
- Function Index
- Function Details

Authors: Richard Carlsson (`richardc@csd.uu.se`).

See also: edoc.

## Description

EDoc documentation extraction.

## Data Types

### filename()

`filename() = file:filename()`

## Function Index

file/4 | Reads a text file and returns the list of tags in the file.
header/3 | Similar to `header/5`, but reads the syntax tree and the comments from the specified file.
header/4 | Extracts EDoc documentation from commented header file syntax trees.
header/5 | Similar to `header/4`, but first inserts the given comments in the syntax trees.
source/3 | Like `source/5`, but reads the syntax tree and the comments from the specified file.
source/4 | Extracts EDoc documentation from commented source code syntax trees.
source/5 | Like `source/4`, but first inserts the given comments in the syntax trees.
text/4 | Returns the list of tags in the text.

## Function Details

### file/4

`file(File::filename(), Context, Env::edoc_env(), Options::option_list()) -> {ok, Tags} | {error, Reason}`

- `Context = overview | package`
- `edoc_env() = edoc_lib:edoc_env()`
- `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/4`. Upon error, `Reason` is an atom returned from the call to `//kernel/file:read_file/1`.

See `text/4` for options.

### header/3

`header(File::filename(), Env::edoc_env(), Options::option_list()) -> {ok, Tags} | {error, Reason}`

- `edoc_env() = edoc_lib:edoc_env()`
- `Tags = [term()]`
- `Reason = term()`

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/4

`header(Forms, File::filename(), Env::edoc_env(), Options::option_list()) -> {ok, Tags} | {error, Reason}`

- `Forms = syntaxTree() | [syntaxTree()]`
- `edoc_env() = edoc_lib:edoc_env()`
- `Tags = [term()]`
- `Reason = term()`

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.

### header/5

`header(Forms, Comments::[comment()], File::filename(), Env::edoc_env(), Options::option_list()) -> {ok, Tags} | {error, Reason}`

- `Forms = syntaxTree() | [syntaxTree()]`
- `edoc_env() = edoc_lib:edoc_env()`
- `Tags = [term()]`
- `Reason = term()`

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.

### source/3

`source(File::filename(), Env::edoc_env(), Options::option_list()) -> {ModuleName, edoc_module()}`

- `ModuleName = atom()`

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/4

`source(Forms, File::filename(), Env::edoc_env(), Options::option_list()) -> {ModuleName, edoc_module()}`

- `Forms = syntaxTree() | [syntaxTree()]`
- `ModuleName = atom()`
- `edoc_module() = edoc:edoc_module()`
- `edoc_env() = edoc_lib:edoc_env()`

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

### source/5

`source(Forms, Comments::[comment()], File::filename(), Env::edoc_env(), Options::option_list()) -> {ModuleName, edoc_module()}`

- `Forms = syntaxTree() | [syntaxTree()]`
- `comment() = {Line, Column, Indentation, Text}`
- `Line = integer()`
- `Column = integer()`
- `Indentation = integer()`
- `Text = [string()]`
- `ModuleName = atom()`

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.

### text/4

`text(Text::string(), Context, Env::edoc_env(), Options::option_list()) -> Tags`

- `Context = overview | package`
- `Tags = [term()]`
- `edoc_env() = edoc_lib:edoc_env()`

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

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