From 7dc58ca03d6c59dadfb6c570b97e05c08644041b Mon Sep 17 00:00:00 2001 From: Richard Carlsson Date: Sat, 21 Apr 2012 01:24:37 +0200 Subject: modernized and cleaned up edoc documentation --- lib/syntax_tools/src/erl_syntax.erl | 1346 +++++++++++++++++------------------ 1 file changed, 642 insertions(+), 704 deletions(-) diff --git a/lib/syntax_tools/src/erl_syntax.erl b/lib/syntax_tools/src/erl_syntax.erl index a3cc8ba084..beae6f4a01 100644 --- a/lib/syntax_tools/src/erl_syntax.erl +++ b/lib/syntax_tools/src/erl_syntax.erl @@ -24,23 +24,20 @@ %% This module defines an abstract data type for representing Erlang %% source code as syntax trees, in a way that is backwards compatible %% with the data structures created by the Erlang standard library -%% parser module erl_parse (often referred to as "parse +%% parser module `erl_parse' (often referred to as "parse %% trees", which is a bit of a misnomer). This means that all -%% erl_parse trees are valid abstract syntax trees, but the +%% `erl_parse' trees are valid abstract syntax trees, but the %% reverse is not true: abstract syntax trees can in general not be used -%% as input to functions expecting an erl_parse tree. +%% as input to functions expecting an `erl_parse' tree. %% However, as long as an abstract syntax tree represents a correct -%% Erlang program, the function revert/1 should be able to -%% transform it to the corresponding erl_parse +%% Erlang program, the function {@link revert/1} should be able to +%% transform it to the corresponding `erl_parse' %% representation. %% -%% A recommended starting point for the first-time user is the -%% documentation of the syntaxTree() data type, and -%% the function type/1. +%% A recommended starting point for the first-time user is the documentation +%% of the {@link syntaxTree()} data type, and the function {@link type/1}. %% -%%

NOTES:

+%% == NOTES: == %% %% This module deals with the composition and decomposition of %% syntactic entities (as opposed to semantic ones); its @@ -50,36 +47,31 @@ %% in general, the user is assumed to pass type-correct arguments - if %% this is not done, the effects are not defined. %% -%% With the exception of the erl_parse data structures, +%% With the exception of the {@link erl_parse()} data structures, %% the internal representations of abstract syntax trees are subject to %% change without notice, and should not be documented outside this %% module. Furthermore, we do not give any guarantees on how an abstract %% syntax tree may or may not be represented, with the following %% exceptions: no syntax tree is represented by a single atom, such -%% as none, by a list constructor [X | Y], or -%% by the empty list []. This can be relied on when writing +%% as `none', by a list constructor `[X | Y]', or +%% by the empty list `[]'. This can be relied on when writing %% functions that operate on syntax trees. -%% @type syntaxTree(). An abstract syntax tree. The -%% erl_parse "parse tree" representation is a subset of the -%% syntaxTree() representation. +%% @type syntaxTree(). An abstract syntax tree. The {@link erl_parse()} +%% "parse tree" representation is a proper subset of the `syntaxTree()' +%% representation. %% %% Every abstract syntax tree node has a type, given by the -%% function type/1. Each node also -%% has associated attributes; see get_attrs/1 for details. The -%% functions make_tree/2 and subtrees/1 are generic +%% function {@link type/1}. Each node also has associated +%% attributes; see {@link get_attrs/1} for details. The functions +%% {@link make_tree/2} and {@link subtrees/1} are generic %% constructor/decomposition functions for abstract syntax trees. The -%% functions abstract/1 and concrete/1 convert between +%% functions {@link abstract/1} and {@link concrete/1} convert between %% constant Erlang terms and their syntactic representations. The set of -%% syntax tree nodes is extensible through the tree/2 function. +%% syntax tree nodes is extensible through the {@link tree/2} function. %% -%% A syntax tree can be transformed to the erl_parse -%% representation with the revert/1 -%% function. +%% A syntax tree can be transformed to the {@link erl_parse()} +%% representation with the {@link revert/1} function. -module(erl_syntax). @@ -396,8 +388,7 @@ -type erl_parse() :: erl_parse:abstract_form() | erl_parse:abstract_expr(). %% The representation built by the Erlang standard library parser -%% `erl_parse'. This is a subset of the `syntaxTree' type. +%% `erl_parse'. This is a subset of the {@link syntaxTree()} type. %% ===================================================================== %% @@ -407,10 +398,11 @@ %% ===================================================================== -%% @doc Returns the type tag of Node. If Node +%% @doc Returns the type tag of `Node'. If `Node' %% does not represent a syntax tree, evaluation fails with reason -%% badarg. Node types currently defined by this module are: -%%

+%% `badarg'. Node types currently defined by this module are: +%% +%%
%% %% %% @@ -477,12 +469,13 @@ %% %% %% -%%
applicationarity_qualifiervariablewarning_marker

-%%

The user may (for special purposes) create additional nodes -%% with other type tags, using the tree/2 function.

+%% +%% +%% The user may (for special purposes) create additional nodes +%% with other type tags, using the {@link tree/2} function. %% -%%

Note: The primary constructor functions for a node type should -%% always have the same name as the node type itself.

+%% Note: The primary constructor functions for a node type should +%% always have the same name as the node type itself. %% %% @see tree/2 %% @see application/3 @@ -607,37 +600,38 @@ type(Node) -> %% ===================================================================== -%% @doc Returns true if Node is a leaf node, -%% otherwise false. The currently recognised leaf node +%% @doc Returns `true' if `Node' is a leaf node, +%% otherwise `false'. The currently recognised leaf node %% types are: -%%

+%% +%%
%% -%% -%% -%% -%% -%% +%% +%% +%% +%% +%% %% -%% -%% -%% -%% -%% +%% +%% +%% +%% +%% %% -%% -%% -%% -%% +%% +%% +%% +%% %% -%%
atomcharcommenteof_markererror_marker`atom'`char'`comment'`eof_marker'`error_marker'
floatintegerniloperatorstring`float'`integer'`nil'`operator'`string'
textunderscorevariablewarning_marker`text'`underscore'`variable'`warning_marker'

-%%

A node of type tuple is a leaf node if and only if -%% its arity is zero.

+%% +%% +%% A node of type `tuple' is a leaf node if and only if its arity is zero. %% -%%

Note: not all literals are leaf nodes, and vice versa. E.g., +%% Note: not all literals are leaf nodes, and vice versa. E.g., %% tuples with nonzero arity and nonempty lists may be literals, but are %% not leaf nodes. Variables, on the other hand, are leaf nodes but not -%% literals.

-%% +%% literals. +%% %% @see type/1 %% @see is_literal/1 @@ -665,27 +659,29 @@ is_leaf(Node) -> %% ===================================================================== -%% @doc Returns true if Node is a syntax tree +%% @doc Returns `true' if `Node' is a syntax tree %% representing a so-called "source code form", otherwise -%% false. Forms are the Erlang source code units which, +%% `false'. Forms are the Erlang source code units which, %% placed in sequence, constitute an Erlang program. Current form types %% are: -%%

+%% +%%
%% -%% -%% -%% -%% -%% +%% +%% +%% +%% +%% %% -%% -%% -%% -%% +%% +%% +%% +%% %% -%%
attributecommenterror_markereof_markerform_list`attribute'`comment'`error_marker'`eof_marker'`form_list'
functionrulewarning_markertext`function'`rule'`warning_marker'`text'

+%% +%% %% @see type/1 -%% @see attribute/2 +%% @see attribute/2 %% @see comment/2 %% @see eof_marker/0 %% @see error_marker/1 @@ -713,7 +709,7 @@ is_form(Node) -> %% ===================================================================== %% @doc Returns the position information associated with -%% Node. This is usually a nonnegative integer (indicating +%% `Node'. This is usually a nonnegative integer (indicating %% the source code line number), but may be any term. By default, all %% new tree nodes have their associated position information set to the %% integer zero. @@ -745,8 +741,7 @@ get_pos(Node) -> %% ===================================================================== -%% @doc Sets the position information of Node to -%% Pos. +%% @doc Sets the position information of `Node' to `Pos'. %% %% @see get_pos/1 %% @see copy_pos/2 @@ -767,11 +762,10 @@ set_pos(Node, Pos) -> %% ===================================================================== -%% @doc Copies the position information from Source to -%% Target. +%% @doc Copies the position information from `Source' to `Target'. %% -%%

This is equivalent to set_pos(Target, -%% get_pos(Source)), but potentially more efficient.

+%% This is equivalent to `set_pos(Target, +%% get_pos(Source))', but potentially more efficient. %% %% @see get_pos/1 %% @see set_pos/2 @@ -805,18 +799,16 @@ set_com(Node, Com) -> %% possibly empty list of abstract comments, in top-down textual order. %% When the code is formatted, pre-comments are typically displayed %% directly above the node. For example: -%% 
-%%         % Pre-comment of function
-%%         foo(X) -> {bar, X}.
+%% ```% Pre-comment of function +%% foo(X) -> {bar, X}.''' %% -%%

If possible, the comment should be moved before any preceding +%% If possible, the comment should be moved before any preceding %% separator characters on the same line. E.g.: -%% 

-%%         foo([X | Xs]) ->
-%%             % Pre-comment of 'bar(X)' node
-%%             [bar(X) | foo(Xs)];
-%%         ...
-%% (where the comment is moved before the "[").

+%% ```foo([X | Xs]) -> +%% % Pre-comment of 'bar(X)' node +%% [bar(X) | foo(Xs)]; +%% ...''' +%% (where the comment is moved before the "`['"). %% %% @see comment/2 %% @see set_precomments/2 @@ -834,8 +826,8 @@ get_precomments_1(#attr{com = #com{pre = Cs}}) -> Cs. %% ===================================================================== -%% @doc Sets the pre-comments of Node to -%% Comments. Comments should be a possibly +%% @doc Sets the pre-comments of `Node' to +%% `Comments'. `Comments' should be a possibly %% empty list of abstract comments, in top-down textual order. %% %% @see comment/2 @@ -865,12 +857,11 @@ set_precomments_1(#attr{com = Com} = Attr, Cs) -> %% ===================================================================== -%% @doc Appends Comments to the pre-comments of -%% Node. +%% @doc Appends `Comments' to the pre-comments of `Node'. %% -%%

Note: This is equivalent to set_precomments(Node, -%% get_precomments(Node) ++ Comments), but potentially more -%% efficient.

+%% Note: This is equivalent to `set_precomments(Node, +%% get_precomments(Node) ++ Comments)', but potentially more +%% efficient. %% %% @see comment/2 %% @see get_precomments/1 @@ -901,18 +892,16 @@ add_precomments_1(Cs, #attr{com = Com} = Attr) -> %% possibly empty list of abstract comments, in top-down textual order. %% When the code is formatted, post-comments are typically displayed to %% the right of and/or below the node. For example: -%% 
-%%         {foo, X, Y}     % Post-comment of tuple
+%% ```{foo, X, Y} % Post-comment of tuple''' %% -%%

If possible, the comment should be moved past any following +%% If possible, the comment should be moved past any following %% separator characters on the same line, rather than placing the %% separators on the following line. E.g.: -%% 

-%%         foo([X | Xs], Y) ->
-%%             foo(Xs, bar(X));     % Post-comment of 'bar(X)' node
-%%          ...
-%% (where the comment is moved past the rightmost ")" and -%% the ";").

+%% ```foo([X | Xs], Y) -> +%% foo(Xs, bar(X)); % Post-comment of 'bar(X)' node +%% ...''' +%% (where the comment is moved past the rightmost "`)'" and +%% the "`;'"). %% %% @see comment/2 %% @see set_postcomments/2 @@ -930,8 +919,8 @@ get_postcomments_1(#attr{com = #com{post = Cs}}) -> Cs. %% ===================================================================== -%% @doc Sets the post-comments of Node to -%% Comments. Comments should be a possibly +%% @doc Sets the post-comments of `Node' to +%% `Comments'. `Comments' should be a possibly %% empty list of abstract comments, in top-down textual order %% %% @see comment/2 @@ -961,12 +950,11 @@ set_postcomments_1(#attr{com = Com} = Attr, Cs) -> %% ===================================================================== -%% @doc Appends Comments to the post-comments of -%% Node. +%% @doc Appends `Comments' to the post-comments of `Node'. %% -%%

Note: This is equivalent to set_postcomments(Node, -%% get_postcomments(Node) ++ Comments), but potentially more -%% efficient.

+%% Note: This is equivalent to `set_postcomments(Node, +%% get_postcomments(Node) ++ Comments)', but potentially more +%% efficient. %% %% @see comment/2 %% @see get_postcomments/1 @@ -993,12 +981,12 @@ add_postcomments_1(Cs, #attr{com = Com} = Attr) -> %% ===================================================================== -%% @doc Yields false if the node has no associated -%% comments, and true otherwise. +%% @doc Yields `false' if the node has no associated +%% comments, and `true' otherwise. %% -%%

Note: This is equivalent to (get_precomments(Node) == []) -%% and (get_postcomments(Node) == []), but potentially more -%% efficient.

+%% Note: This is equivalent to `(get_precomments(Node) == []) +%% and (get_postcomments(Node) == [])', but potentially more +%% efficient. %% %% @see get_precomments/1 %% @see get_postcomments/1 @@ -1022,11 +1010,11 @@ has_comments(_) -> false. %% ===================================================================== -%% @doc Clears the associated comments of Node. +%% @doc Clears the associated comments of `Node'. %% -%%

Note: This is equivalent to -%% set_precomments(set_postcomments(Node, []), []), but -%% potentially more efficient.

+%% Note: This is equivalent to +%% `set_precomments(set_postcomments(Node, []), [])', but +%% potentially more efficient. %% %% @see set_precomments/2 %% @see set_postcomments/2 @@ -1045,13 +1033,12 @@ remove_comments(Node) -> %% ===================================================================== -%% @doc Copies the pre- and postcomments from Source to -%% Target. +%% @doc Copies the pre- and postcomments from `Source' to `Target'. %% -%%

Note: This is equivalent to -%% set_postcomments(set_precomments(Target, -%% get_precomments(Source)), get_postcomments(Source)), but -%% potentially more efficient.

+%% Note: This is equivalent to +%% `set_postcomments(set_precomments(Target, +%% get_precomments(Source)), get_postcomments(Source))', but +%% potentially more efficient. %% %% @see comment/2 %% @see get_precomments/1 @@ -1066,13 +1053,13 @@ copy_comments(Source, Target) -> %% ===================================================================== -%% @doc Appends the comments of Source to the current -%% comments of Target. +%% @doc Appends the comments of `Source' to the current +%% comments of `Target'. %% -%%

Note: This is equivalent to -%% add_postcomments(get_postcomments(Source), -%% add_precomments(get_precomments(Source), Target)), but -%% potentially more efficient.

+%% Note: This is equivalent to +%% `add_postcomments(get_postcomments(Source), +%% add_precomments(get_precomments(Source), Target))', but +%% potentially more efficient. %% %% @see comment/2 %% @see get_precomments/1 @@ -1104,8 +1091,7 @@ get_ann(_) -> []. %% ===================================================================== -%% @doc Sets the list of user annotations of Node to -%% Annotations. +%% @doc Sets the list of user annotations of `Node' to `Annotations'. %% %% @see get_ann/1 %% @see add_ann/2 @@ -1127,11 +1113,11 @@ set_ann(Node, As) -> %% ===================================================================== -%% @doc Appends the term Annotation to the list of user -%% annotations of Node. +%% @doc Appends the term `Annotation' to the list of user +%% annotations of `Node'. %% -%%

Note: this is equivalent to set_ann(Node, [Annotation | -%% get_ann(Node)]), but potentially more efficient.

+%% Note: this is equivalent to `set_ann(Node, [Annotation | +%% get_ann(Node)])', but potentially more efficient. %% %% @see get_ann/1 %% @see set_ann/2 @@ -1152,11 +1138,10 @@ add_ann(A, Node) -> %% ===================================================================== -%% @doc Copies the list of user annotations from Source to -%% Target. +%% @doc Copies the list of user annotations from `Source' to `Target'. %% -%%

Note: this is equivalent to set_ann(Target, -%% get_ann(Source)), but potentially more efficient.

+%% Note: this is equivalent to `set_ann(Target, +%% get_ann(Source))', but potentially more efficient. %% %% @see get_ann/1 %% @see set_ann/2 @@ -1173,16 +1158,15 @@ copy_ann(Source, Target) -> %% can be attached to a node. Currently, this includes position %% information, source code comments, and user annotations. The result %% of this function cannot be inspected directly; only attached to -%% another node (cf. set_attrs/2). +%% another node (see {@link set_attrs/2}). %% -%%

For accessing individual attributes, see get_pos/1, -%% get_ann/1, get_precomments/1 and -%% get_postcomments/1.

+%% For accessing individual attributes, see {@link get_pos/1}, +%% {@link get_ann/1}, {@link get_precomments/1} and +%% {@link get_postcomments/1}. %% %% @type syntaxTreeAttributes(). This is an abstract representation of -%% syntax tree node attributes; see the function get_attrs/1. -%% +%% syntax tree node attributes; see the function {@link get_attrs/1}. +%% %% @see set_attrs/2 %% @see get_pos/1 %% @see get_ann/1 @@ -1199,8 +1183,7 @@ get_attrs(Node) -> #attr{pos = get_pos(Node), %% ===================================================================== -%% @doc Sets the attributes of Node to -%% Attributes. +%% @doc Sets the attributes of `Node' to `Attributes'. %% %% @see get_attrs/1 %% @see copy_attrs/2 @@ -1219,11 +1202,10 @@ set_attrs(Node, Attr) -> %% ===================================================================== -%% @doc Copies the attributes from Source to -%% Target. +%% @doc Copies the attributes from `Source' to `Target'. %% -%%

Note: this is equivalent to set_attrs(Target, -%% get_attrs(Source)), but potentially more efficient.

+%% Note: this is equivalent to `set_attrs(Target, +%% get_attrs(Source))', but potentially more efficient. %% %% @see get_attrs/1 %% @see set_attrs/2 @@ -1245,18 +1227,18 @@ comment(Strings) -> %% ===================================================================== %% @doc Creates an abstract comment with the given padding and text. If -%% Strings is a (possibly empty) list +%% `Strings' is a (possibly empty) list %% ["Txt1", ..., "TxtN"], the result %% represents the source code text %% 
-%%     %Txt1
-%%     ...
-%%     %TxtN
-%% Padding states the number of empty character positions +%% %Txt1 +%% ... +%% %TxtN +%% `Padding' states the number of empty character positions %% to the left of the comment separating it horizontally from -%% source code on the same line (if any). If Padding is -%% none, a default positive number is used. If -%% Padding is an integer less than 1, there should be no +%% source code on the same line (if any). If `Padding' is +%% `none', a default positive number is used. If +%% `Padding' is an integer less than 1, there should be no %% separating space. Comments are in themselves regarded as source %% program forms. %% @@ -1292,8 +1274,7 @@ comment_text(Node) -> %% ===================================================================== %% @doc Returns the amount of padding before the comment, or -%% none. The latter means that a default padding may be -%% used. +%% `none'. The latter means that a default padding may be used. %% %% @see comment/2 @@ -1305,20 +1286,20 @@ comment_padding(Node) -> %% ===================================================================== %% @doc Creates an abstract sequence of "source code forms". If -%% Forms is [F1, ..., Fn], where each -%% Fi is a form (cf. is_form/1, the result +%% `Forms' is `[F1, ..., Fn]', where each +%% `Fi' is a form (see {@link is_form/1}, the result %% represents %% 
-%%     F1
-%%     ...
-%%     Fn
-%% where the Fi are separated by one or more line breaks. A -%% node of type form_list is itself regarded as a source -%% code form; cf. flatten_form_list/1. -%% -%%

Note: this is simply a way of grouping source code forms as a +%% F1 +%% ... +%% Fn +%% where the `Fi' are separated by one or more line breaks. A +%% node of type `form_list' is itself regarded as a source +%% code form; see {@link flatten_form_list/1}. +%% +%% Note: this is simply a way of grouping source code forms as a %% single syntax tree, usually in order to form an Erlang module -%% definition.

+%% definition. %% %% @see form_list_elements/1 %% @see is_form/1 @@ -1337,7 +1318,7 @@ form_list(Forms) -> %% ===================================================================== -%% @doc Returns the list of subnodes of a form_list node. +%% @doc Returns the list of subnodes of a `form_list' node. %% %% @see form_list/1 @@ -1348,8 +1329,8 @@ form_list_elements(Node) -> %% ===================================================================== -%% @doc Flattens sublists of a form_list node. Returns -%% Node with all subtrees of type form_list +%% @doc Flattens sublists of a `form_list' node. Returns +%% `Node' with all subtrees of type `form_list' %% recursively expanded, yielding a single "flat" abstract form %% sequence. %% @@ -1376,7 +1357,7 @@ flatten_form_list_1([], As) -> %% ===================================================================== %% @doc Creates an abstract piece of source code text. The result -%% represents exactly the sequence of characters in String. +%% represents exactly the sequence of characters in `String'. %% This is useful in cases when one wants full control of the resulting %% output, e.g., for the appearance of floating-point numbers or macro %% definitions. @@ -1393,8 +1374,7 @@ text(String) -> %% ===================================================================== -%% @doc Returns the character sequence represented by a -%% text node. +%% @doc Returns the character sequence represented by a `text' node. %% %% @see text/1 @@ -1406,14 +1386,14 @@ text_string(Node) -> %% ===================================================================== %% @doc Creates an abstract variable with the given name. -%% Name may be any atom or string that represents a +%% `Name' may be any atom or string that represents a %% lexically valid variable name, but not a single underscore -%% character; cf. underscore/0. +%% character; see {@link underscore/0}. %% -%%

Note: no checking is done whether the character sequence +%% Note: no checking is done whether the character sequence %% represents a proper variable name, i.e., whether or not its first %% character is an uppercase Erlang character, or whether it does not -%% contain control characters, whitespace, etc.

+%% contain control characters, whitespace, etc. %% %% @see variable_name/1 %% @see variable_literal/1 @@ -1442,7 +1422,7 @@ revert_variable(Node) -> %% ===================================================================== -%% @doc Returns the name of a variable node as an atom. +%% @doc Returns the name of a `variable' node as an atom. %% %% @see variable/1 @@ -1458,7 +1438,7 @@ variable_name(Node) -> %% ===================================================================== -%% @doc Returns the name of a variable node as a string. +%% @doc Returns the name of a `variable' node as a string. %% %% @see variable/1 @@ -1474,7 +1454,7 @@ variable_literal(Node) -> %% ===================================================================== -%% @doc Creates an abstract universal pattern ("_"). The +%% @doc Creates an abstract universal pattern ("`_'"). The %% lexical representation is a single underscore character. Note that %% this is not a variable, lexically speaking. %% @@ -1499,7 +1479,7 @@ revert_underscore(Node) -> %% ===================================================================== %% @doc Creates an abstract integer literal. The lexical representation -%% is the canonical decimal numeral of Value. +%% is the canonical decimal numeral of `Value'. %% %% @see integer_value/1 %% @see integer_literal/1 @@ -1525,9 +1505,8 @@ revert_integer(Node) -> %% ===================================================================== -%% @doc Returns true if Node has type -%% integer and represents Value, otherwise -%% false. +%% @doc Returns `true' if `Node' has type +%% `integer' and represents `Value', otherwise `false'. %% %% @see integer/1 @@ -1545,7 +1524,7 @@ is_integer(Node, Value) -> %% ===================================================================== -%% @doc Returns the value represented by an integer node. +%% @doc Returns the value represented by an `integer' node. %% %% @see integer/1 @@ -1561,8 +1540,7 @@ integer_value(Node) -> %% ===================================================================== -%% @doc Returns the numeral string represented by an -%% integer node. +%% @doc Returns the numeral string represented by an `integer' node. %% %% @see integer/1 @@ -1574,8 +1552,7 @@ integer_literal(Node) -> %% ===================================================================== %% @doc Creates an abstract floating-point literal. The lexical -%% representation is the decimal floating-point numeral of -%% Value. +%% representation is the decimal floating-point numeral of `Value'. %% %% @see float_value/1 %% @see float_literal/1 @@ -1610,7 +1587,7 @@ revert_float(Node) -> %% ===================================================================== -%% @doc Returns the value represented by a float node. Note +%% @doc Returns the value represented by a `float' node. Note %% that floating-point values should usually not be compared for %% equality. %% @@ -1628,8 +1605,7 @@ float_value(Node) -> %% ===================================================================== -%% @doc Returns the numeral string represented by a float -%% node. +%% @doc Returns the numeral string represented by a `float' node. %% %% @see float/1 @@ -1641,14 +1617,14 @@ float_literal(Node) -> %% ===================================================================== %% @doc Creates an abstract character literal. The result represents -%% "$Name", where Name corresponds to -%% Value. +%% "$Name", where `Name' corresponds to +%% `Value'. %% -%%

Note: the literal corresponding to a particular character value is -%% not uniquely defined. E.g., the character "a" can be -%% written both as "$a" and "$\141", and a Tab -%% character can be written as "$\11", "$\011" -%% or "$\t".

+%% Note: the literal corresponding to a particular character value is +%% not uniquely defined. E.g., the character "`a'" can be +%% written both as "`$a'" and "`$\141'", and a Tab +%% character can be written as "`$\11'", "`$\011'" +%% or "`$\t'". %% %% @see char_value/1 %% @see char_literal/1 @@ -1674,9 +1650,8 @@ revert_char(Node) -> %% ===================================================================== -%% @doc Returns true if Node has type -%% char and represents Value, otherwise -%% false. +%% @doc Returns `true' if `Node' has type +%% `char' and represents `Value', otherwise `false'. %% %% @see char/1 @@ -1694,7 +1669,7 @@ is_char(Node, Value) -> %% ===================================================================== -%% @doc Returns the value represented by a char node. +%% @doc Returns the value represented by a `char' node. %% %% @see char/1 @@ -1710,8 +1685,8 @@ char_value(Node) -> %% ===================================================================== -%% @doc Returns the literal string represented by a char -%% node. This includes the leading "$" character. +%% @doc Returns the literal string represented by a `char' +%% node. This includes the leading "`$'" character. %% %% @see char/1 @@ -1724,12 +1699,12 @@ char_literal(Node) -> %% ===================================================================== %% @doc Creates an abstract string literal. The result represents %% "Text" (including the surrounding -%% double-quotes), where Text corresponds to the sequence -%% of characters in Value, but not representing a -%% specific string literal. E.g., the result of -%% string("x\ny") represents any and all of -%% "x\ny", "x\12y", "x\012y" and -%% "x\^Jy"; cf. char/1. +%% double-quotes), where `Text' corresponds to the sequence +%% of characters in `Value', but not representing a +%% specific string literal. +%% +%% For example, the result of `string("x\ny")' represents any and all of +%% `"x\ny"', `"x\12y"', `"x\012y"' and `"x\^Jy"'; see {@link char/1}. %% %% @see string_value/1 %% @see string_literal/1 @@ -1756,9 +1731,8 @@ revert_string(Node) -> %% ===================================================================== -%% @doc Returns true if Node has type -%% string and represents Value, otherwise -%% false. +%% @doc Returns `true' if `Node' has type +%% `string' and represents `Value', otherwise `false'. %% %% @see string/1 @@ -1776,7 +1750,7 @@ is_string(Node, Value) -> %% ===================================================================== -%% @doc Returns the value represented by a string node. +%% @doc Returns the value represented by a `string' node. %% %% @see string/1 @@ -1792,7 +1766,7 @@ string_value(Node) -> %% ===================================================================== -%% @doc Returns the literal string represented by a string +%% @doc Returns the literal string represented by a `string' %% node. This includes surrounding double-quote characters. %% %% @see string/1 @@ -1805,7 +1779,7 @@ string_literal(Node) -> %% ===================================================================== %% @doc Creates an abstract atom literal. The print name of the atom is -%% the character sequence represented by Name. +%% the character sequence represented by `Name'. %% %% @see atom_value/1 %% @see atom_name/1 @@ -1834,9 +1808,8 @@ revert_atom(Node) -> %% ===================================================================== -%% @doc Returns true if Node has type -%% atom and represents Value, otherwise -%% false. +%% @doc Returns `true' if `Node' has type +%% `atom' and represents `Value', otherwise `false'. %% %% @see atom/1 @@ -1854,7 +1827,7 @@ is_atom(Node, Value) -> %% ===================================================================== -%% @doc Returns the value represented by an atom node. +%% @doc Returns the value represented by an `atom' node. %% %% @see atom/1 @@ -1870,7 +1843,7 @@ atom_value(Node) -> %% ===================================================================== -%% @doc Returns the printname of an atom node. +%% @doc Returns the printname of an `atom' node. %% %% @see atom/1 @@ -1881,13 +1854,12 @@ atom_name(Node) -> %% ===================================================================== -%% @doc Returns the literal string represented by an atom +%% @doc Returns the literal string represented by an `atom' %% node. This includes surrounding single-quote characters if necessary. %% -%%

Note that e.g. the result of atom("x\ny") represents -%% any and all of 'x\ny', 'x\12y', -%% 'x\012y' and 'x\^Jy\'; cf. -%% string/1.

+%% Note that e.g. the result of `atom("x\ny")' represents +%% any and all of `'x\ny'', `'x\12y'', +%% `'x\012y'' and `'x\^Jy\''; see {@link string/1}. %% %% @see atom/1 %% @see string/1 @@ -1899,12 +1871,12 @@ atom_literal(Node) -> %% ===================================================================== -%% @doc Creates an abstract tuple. If Elements is -%% [X1, ..., Xn], the result represents +%% @doc Creates an abstract tuple. If `Elements' is +%% `[X1, ..., Xn]', the result represents %% "{X1, ..., Xn}". %% -%%

Note: The Erlang language has distinct 1-tuples, i.e., -%% {X} is always distinct from X itself.

+%% Note: The Erlang language has distinct 1-tuples, i.e., +%% `{X}' is always distinct from `X' itself. %% %% @see tuple_elements/1 %% @see tuple_size/1 @@ -1931,8 +1903,7 @@ revert_tuple(Node) -> %% ===================================================================== -%% @doc Returns the list of element subtrees of a tuple -%% node. +%% @doc Returns the list of element subtrees of a `tuple' node. %% %% @see tuple/1 @@ -1948,11 +1919,11 @@ tuple_elements(Node) -> %% ===================================================================== -%% @doc Returns the number of elements of a tuple node. +%% @doc Returns the number of elements of a `tuple' node. %% -%%

Note: this is equivalent to -%% length(tuple_elements(Node)), but potentially more -%% efficient.

+%% Note: this is equivalent to +%% `length(tuple_elements(Node))', but potentially more +%% efficient. %% %% @see tuple/1 %% @see tuple_elements/1 @@ -1974,30 +1945,30 @@ list(List) -> %% ===================================================================== %% @doc Constructs an abstract list skeleton. The result has type -%% list or nil. If List is a -%% nonempty list [E1, ..., En], the result has type -%% list and represents either "[E1, ..., -%% En]", if Tail is none, or +%% `list' or `nil'. If `List' is a +%% nonempty list `[E1, ..., En]', the result has type +%% `list' and represents either "[E1, ..., +%% En]", if `Tail' is `none', or %% otherwise "[E1, ..., En | -%% Tail]". If List is the empty list, -%% Tail must be none, and in that -%% case the result has type nil and represents -%% "[]" (cf. nil/0). +%% Tail]". If `List' is the empty list, +%% `Tail' must be `none', and in that +%% case the result has type `nil' and represents +%% "`[]'" (see {@link nil/0}). %% -%%

The difference between lists as semantic objects (built up of +%% The difference between lists as semantic objects (built up of %% individual "cons" and "nil" terms) and the various syntactic forms %% for denoting lists may be bewildering at first. This module provides %% functions both for exact control of the syntactic representation as %% well as for the simple composition and deconstruction in terms of -%% cons and head/tail operations.

+%% cons and head/tail operations. %% -%%

Note: in list(Elements, none), the "nil" list -%% terminator is implicit and has no associated information (cf. -%% get_attrs/1), while in the seemingly equivalent -%% list(Elements, Tail) when Tail has type -%% nil, the list terminator subtree Tail may +%% Note: in `list(Elements, none)', the "nil" list +%% terminator is implicit and has no associated information (see +%% {@link get_attrs/1}), while in the seemingly equivalent +%% `list(Elements, Tail)' when `Tail' has type +%% `nil', the list terminator subtree `Tail' may %% have attached attributes such as position, comments, and annotations, -%% which will be preserved in the result.

+%% which will be preserved in the result. %% %% @see nil/0 %% @see list/1 @@ -2055,7 +2026,7 @@ revert_list(Node) -> %% ===================================================================== %% @doc Creates an abstract empty list. The result represents -%% "[]". The empty list is traditionally called "nil". +%% "`[]'". The empty list is traditionally called "nil". %% %% @see list/2 %% @see is_list_skeleton/1 @@ -2078,11 +2049,11 @@ revert_nil(Node) -> %% ===================================================================== -%% @doc Returns the prefix element subtrees of a list node. -%% If Node represents "[E1, ..., +%% @doc Returns the prefix element subtrees of a `list' node. +%% If `Node' represents "[E1, ..., %% En]" or "[E1, ..., En | -%% Tail]", the returned value is [E1, ..., -%% En]. +%% Tail]", the returned value is `[E1, ..., +%% En]'. %% %% @see list/2 @@ -2098,18 +2069,17 @@ list_prefix(Node) -> %% ===================================================================== -%% @doc Returns the suffix subtree of a list node, if one -%% exists. If Node represents "[E1, ..., +%% @doc Returns the suffix subtree of a `list' node, if one +%% exists. If `Node' represents "[E1, ..., %% En | Tail]", the returned value is -%% Tail, otherwise, i.e., if Node represents -%% "[E1, ..., En]", none is +%% `Tail', otherwise, i.e., if `Node' represents +%% "[E1, ..., En]", `none' is %% returned. %% -%%

Note that even if this function returns some Tail -%% that is not none, the type of Tail can be -%% nil, if the tail has been given explicitly, and the list -%% skeleton has not been compacted (cf. -%% compact_list/1).

+%% Note that even if this function returns some `Tail' +%% that is not `none', the type of `Tail' can be +%% `nil', if the tail has been given explicitly, and the list +%% skeleton has not been compacted (see {@link compact_list/1}). %% %% @see list/2 %% @see nil/0 @@ -2135,17 +2105,17 @@ list_suffix(Node) -> %% ===================================================================== %% @doc "Optimising" list skeleton cons operation. Creates an abstract -%% list skeleton whose first element is Head and whose tail -%% corresponds to Tail. This is similar to -%% list([Head], Tail), except that Tail may -%% not be none, and that the result does not necessarily +%% list skeleton whose first element is `Head' and whose tail +%% corresponds to `Tail'. This is similar to +%% `list([Head], Tail)', except that `Tail' may +%% not be `none', and that the result does not necessarily %% represent exactly "[Head | Tail]", but -%% may depend on the Tail subtree. E.g., if -%% Tail represents [X, Y], the result may +%% may depend on the `Tail' subtree. E.g., if +%% `Tail' represents `[X, Y]', the result may %% represent "[Head, X, Y]", rather than %% "[Head | [X, Y]]". Annotations on -%% Tail itself may be lost if Tail represents -%% a list skeleton, but comments on Tail are propagated to +%% `Tail' itself may be lost if `Tail' represents +%% a list skeleton, but comments on `Tail' are propagated to %% the result. %% %% @see list/2 @@ -2167,8 +2137,8 @@ cons(Head, Tail) -> %% ===================================================================== -%% @doc Returns the head element subtree of a list node. If -%% Node represents "[Head ...]", the +%% @doc Returns the head element subtree of a `list' node. If +%% `Node' represents "[Head ...]", the %% result will represent "Head". %% %% @see list/2 @@ -2182,13 +2152,13 @@ list_head(Node) -> %% ===================================================================== -%% @doc Returns the tail of a list node. If -%% Node represents a single-element list +%% @doc Returns the tail of a `list' node. If +%% `Node' represents a single-element list %% "[E]", then the result has type -%% nil, representing "[]". If -%% Node represents "[E1, E2 +%% `nil', representing "`[]'". If +%% `Node' represents "[E1, E2 %% ...]", the result will represent "[E2 -%% ...]", and if Node represents +%% ...]", and if `Node' represents %% "[Head | Tail]", the result will %% represent "Tail". %% @@ -2213,8 +2183,8 @@ list_tail(Node) -> %% ===================================================================== -%% @doc Returns true if Node has type -%% list or nil, otherwise false. +%% @doc Returns `true' if `Node' has type +%% `list' or `nil', otherwise `false'. %% %% @see list/2 %% @see nil/0 @@ -2230,22 +2200,22 @@ is_list_skeleton(Node) -> %% ===================================================================== -%% @doc Returns true if Node represents a -%% proper list, and false otherwise. A proper list is a -%% list skeleton either on the form "[]" or +%% @doc Returns `true' if `Node' represents a +%% proper list, and `false' otherwise. A proper list is a +%% list skeleton either on the form "`[]'" or %% "[E1, ..., En]", or "[... | -%% Tail]" where recursively Tail also +%% Tail]" where recursively `Tail' also %% represents a proper list. %% -%%

Note: Since Node is a syntax tree, the actual +%% Note: Since `Node' is a syntax tree, the actual %% run-time values corresponding to its subtrees may often be partially -%% or completely unknown. Thus, if Node represents e.g. -%% "[... | Ns]" (where Ns is a variable), then -%% the function will return false, because it is not known -%% whether Ns will be bound to a list at run-time. If -%% Node instead represents e.g. "[1, 2, 3]" or -%% "[A | []]", then the function will return -%% true.

+%% or completely unknown. Thus, if `Node' represents e.g. +%% "`[... | Ns]'" (where `Ns' is a variable), then +%% the function will return `false', because it is not known +%% whether `Ns' will be bound to a list at run-time. If +%% `Node' instead represents e.g. "`[1, 2, 3]'" or +%% "`[A | []]'", then the function will return +%% `true'. %% %% @see list/2 @@ -2269,11 +2239,10 @@ is_proper_list(Node) -> %% ===================================================================== %% @doc Returns the list of element subtrees of a list skeleton. -%% Node must represent a proper list. E.g., if -%% Node represents "[X1, X2 | +%% `Node' must represent a proper list. E.g., if +%% `Node' represents "[X1, X2 | %% [X3, X4 | []]", then -%% list_elements(Node) yields the list [X1, X2, X3, -%% X4]. +%% `list_elements(Node)' yields the list `[X1, X2, X3, X4]'. %% %% @see list/2 %% @see is_proper_list/1 @@ -2300,14 +2269,14 @@ list_elements(Node, As) -> %% ===================================================================== %% @doc Returns the number of element subtrees of a list skeleton. -%% Node must represent a proper list. E.g., if -%% Node represents "[X1 | [X2, X3 | [X4, X5, -%% X6]]]", then list_length(Node) returns the +%% `Node' must represent a proper list. E.g., if +%% `Node' represents "`[X1 | [X2, X3 | [X4, X5, +%% X6]]]'", then `list_length(Node)' returns the %% integer 6. %% -%%

Note: this is equivalent to -%% length(list_elements(Node)), but potentially more -%% efficient.

+%% Note: this is equivalent to +%% `length(list_elements(Node))', but potentially more +%% efficient. %% %% @see list/2 %% @see is_proper_list/1 @@ -2335,15 +2304,15 @@ list_length(Node, A) -> %% ===================================================================== %% @doc Expands an abstract list skeleton to its most explicit form. If -%% Node represents "[E1, ..., En | +%% `Node' represents "[E1, ..., En | %% Tail]", the result represents "[E1 | %% ... [En | Tail1] ... ]", where -%% Tail1 is the result of -%% normalize_list(Tail). If Node represents +%% `Tail1' is the result of +%% `normalize_list(Tail)'. If `Node' represents %% "[E1, ..., En]", the result simply %% represents "[E1 | ... [En | []] ... -%% ]". If Node does not represent a list skeleton, -%% Node itself is returned. +%% ]". If `Node' does not represent a list skeleton, +%% `Node' itself is returned. %% %% @see list/2 %% @see compact_list/1 @@ -2375,12 +2344,12 @@ normalize_list_1(Es, Tail) -> %% ===================================================================== %% @doc Yields the most compact form for an abstract list skeleton. The %% result either represents "[E1, ..., En | -%% Tail]", where Tail is not a list +%% Tail]", where `Tail' is not a list %% skeleton, or otherwise simply "[E1, ..., -%% En]". Annotations on subtrees of Node +%% En]". Annotations on subtrees of `Node' %% that represent list skeletons may be lost, but comments will be -%% propagated to the result. Returns Node itself if -%% Node does not represent a list skeleton. +%% propagated to the result. Returns `Node' itself if +%% `Node' does not represent a list skeleton. %% %% @see list/2 %% @see normalize_list/1 @@ -2419,7 +2388,7 @@ compact_list(Node) -> %% ===================================================================== %% @doc Creates an abstract binary-object template. If -%% Fields is [F1, ..., Fn], the result +%% `Fields' is `[F1, ..., Fn]', the result %% represents "<<F1, ..., %% Fn>>". %% @@ -2452,8 +2421,7 @@ revert_binary(Node) -> %% ===================================================================== -%% @doc Returns the list of field subtrees of a binary -%% node. +%% @doc Returns the list of field subtrees of a `binary' node. %% %% @see binary/1 %% @see binary_field/2 @@ -2480,10 +2448,10 @@ binary_field(Body) -> %% ===================================================================== %% @doc Creates an abstract binary template field. -%% If Size is none, this is equivalent to -%% "binary_field(Body, Types)", otherwise it is -%% equivalent to "binary_field(size_qualifier(Body, Size), -%% Types)". +%% If `Size' is `none', this is equivalent to +%% "`binary_field(Body, Types)'", otherwise it is +%% equivalent to "`binary_field(size_qualifier(Body, Size), +%% Types)'". %% %% (This is a utility function.) %% @@ -2502,9 +2470,9 @@ binary_field(Body, Size, Types) -> %% ===================================================================== %% @doc Creates an abstract binary template field. If -%% Types is the empty list, the result simply represents -%% "Body", otherwise, if Types is -%% [T1, ..., Tn], the result represents +%% `Types' is the empty list, the result simply represents +%% "Body", otherwise, if `Types' is +%% `[T1, ..., Tn]', the result represents %% "Body/T1-...-Tn". %% %% @see binary/1 @@ -2558,7 +2526,7 @@ revert_binary_field(Node) -> %% ===================================================================== -%% @doc Returns the body subtree of a binary_field. +%% @doc Returns the body subtree of a `binary_field'. %% %% @see binary_field/2 @@ -2579,9 +2547,9 @@ binary_field_body(Node) -> %% ===================================================================== %% @doc Returns the list of type-specifier subtrees of a -%% binary_field node. If Node represents +%% `binary_field' node. If `Node' represents %% ".../T1, ..., Tn", the result is -%% [T1, ..., Tn], otherwise the result is the empty list. +%% `[T1, ..., Tn]', otherwise the result is the empty list. %% %% @see binary_field/2 @@ -2602,11 +2570,11 @@ binary_field_types(Node) -> %% ===================================================================== %% @doc Returns the size specifier subtree of a -%% binary_field node, if any. If Node +%% `binary_field' node, if any. If `Node' %% represents "Body:Size" or %% "Body:Size/T1, ..., -%% Tn", the result is Size, otherwise -%% none is returned. +%% Tn", the result is `Size', otherwise +%% `none' is returned. %% %% (This is a utility function.) %% @@ -2656,8 +2624,7 @@ size_qualifier(Body, Size) -> %% ===================================================================== -%% @doc Returns the body subtree of a size_qualifier -%% node. +%% @doc Returns the body subtree of a `size_qualifier' node. %% %% @see size_qualifier/2 @@ -2669,7 +2636,7 @@ size_qualifier_body(Node) -> %% ===================================================================== %% @doc Returns the argument subtree (the size) of a -%% size_qualifier node. +%% `size_qualifier' node. %% %% @see size_qualifier/2 @@ -2682,12 +2649,12 @@ size_qualifier_argument(Node) -> %% ===================================================================== %% @doc Creates an abstract error marker. The result represents an %% occurrence of an error in the source code, with an associated Erlang -%% I/O ErrorInfo structure given by Error (see module +%% I/O ErrorInfo structure given by `Error' (see module %% {@link //stdlib/io} for details). Error markers are regarded as source %% code forms, but have no defined lexical form. %% -%%

Note: this is supported only for backwards compatibility with -%% existing parsers and tools.

+%% Note: this is supported only for backwards compatibility with +%% existing parsers and tools. %% %% @see error_marker_info/1 %% @see warning_marker/1 @@ -2718,8 +2685,7 @@ revert_error_marker(Node) -> %% ===================================================================== -%% @doc Returns the ErrorInfo structure of an error_marker -%% node. +%% @doc Returns the ErrorInfo structure of an `error_marker' node. %% %% @see error_marker/1 @@ -2737,12 +2703,12 @@ error_marker_info(Node) -> %% ===================================================================== %% @doc Creates an abstract warning marker. The result represents an %% occurrence of a possible problem in the source code, with an -%% associated Erlang I/O ErrorInfo structure given by Error +%% associated Erlang I/O ErrorInfo structure given by `Error' %% (see module {@link //stdlib/io} for details). Warning markers are %% regarded as source code forms, but have no defined lexical form. %% -%%

Note: this is supported only for backwards compatibility with -%% existing parsers and tools.

+%% Note: this is supported only for backwards compatibility with +%% existing parsers and tools. %% %% @see warning_marker_info/1 %% @see error_marker/1 @@ -2773,8 +2739,7 @@ revert_warning_marker(Node) -> %% ===================================================================== -%% @doc Returns the ErrorInfo structure of a warning_marker -%% node. +%% @doc Returns the ErrorInfo structure of a `warning_marker' node. %% %% @see warning_marker/1 @@ -2796,8 +2761,8 @@ warning_marker_info(Node) -> %% (namely, the last in any sequence in which it occurs). It has no %% defined lexical form. %% -%%

Note: this is retained only for backwards compatibility with -%% existing parsers and tools.

+%% Note: this is retained only for backwards compatibility with +%% existing parsers and tools. %% %% @see error_marker/1 %% @see warning_marker/1 @@ -2831,19 +2796,19 @@ attribute(Name) -> %% ===================================================================== %% @doc Creates an abstract program attribute. If -%% Arguments is [A1, ..., An], the result +%% `Arguments' is `[A1, ..., An]', the result %% represents "-Name(A1, ..., -%% An).". Otherwise, if Arguments is -%% none, the result represents +%% An).". Otherwise, if `Arguments' is +%% `none', the result represents %% "-Name.". The latter form makes it possible %% to represent preprocessor directives such as -%% "-endif.". Attributes are source code forms. +%% "`-endif.'". Attributes are source code forms. %% -%%

Note: The preprocessor macro definition directive +%% Note: The preprocessor macro definition directive %% "-define(Name, Body)." has relatively -%% few requirements on the syntactical form of Body (viewed -%% as a sequence of tokens). The text node type can be used -%% for a Body that is not a normal Erlang construct.

+%% few requirements on the syntactical form of `Body' (viewed +%% as a sequence of tokens). The `text' node type can be used +%% for a `Body' that is not a normal Erlang construct. %% %% @see attribute/1 %% @see attribute_name/1 @@ -3037,7 +3002,7 @@ revert_module_name(A) -> %% ===================================================================== -%% @doc Returns the name subtree of an attribute node. +%% @doc Returns the name subtree of an `attribute' node. %% %% @see attribute/1 @@ -3054,11 +3019,11 @@ attribute_name(Node) -> %% ===================================================================== %% @doc Returns the list of argument subtrees of an -%% attribute node, if any. If Node +%% `attribute' node, if any. If `Node' %% represents "-Name.", the result is -%% none. Otherwise, if Node represents +%% `none'. Otherwise, if `Node' represents %% "-Name(E1, ..., En).", -%% [E1, ..., E1] is returned. +%% `[E1, ..., E1]' is returned. %% %% @see attribute/1 @@ -3146,8 +3111,7 @@ arity_qualifier(Body, Arity) -> %% ===================================================================== -%% @doc Returns the body subtree of an arity_qualifier -%% node. +%% @doc Returns the body subtree of an `arity_qualifier' node. %% %% @see arity_qualifier/2 @@ -3159,7 +3123,7 @@ arity_qualifier_body(Node) -> %% ===================================================================== %% @doc Returns the argument (the arity) subtree of an -%% arity_qualifier node. +%% `arity_qualifier' node. %% %% @see arity_qualifier/2 @@ -3204,7 +3168,7 @@ revert_module_qualifier(Node) -> %% ===================================================================== %% @doc Returns the argument (the module) subtree of a -%% module_qualifier node. +%% `module_qualifier' node. %% %% @see module_qualifier/2 @@ -3220,8 +3184,7 @@ module_qualifier_argument(Node) -> %% ===================================================================== -%% @doc Returns the body subtree of a module_qualifier -%% node. +%% @doc Returns the body subtree of a `module_qualifier' node. %% %% @see module_qualifier/2 @@ -3239,7 +3202,7 @@ module_qualifier_body(Node) -> %% ===================================================================== %% @doc Creates an abstract qualified name. The result represents %% "S1.S2. ... .Sn", if -%% Segments is [S1, S2, ..., Sn]. +%% `Segments' is `[S1, S2, ..., Sn]'. %% %% @see qualified_name_segments/1 @@ -3268,7 +3231,7 @@ revert_qualified_name(Node) -> %% ===================================================================== %% @doc Returns the list of name segments of a -%% qualified_name node. +%% `qualified_name' node. %% %% @see qualified_name/1 @@ -3284,10 +3247,10 @@ qualified_name_segments(Node) -> %% ===================================================================== -%% @doc Creates an abstract function definition. If Clauses -%% is [C1, ..., Cn], the result represents +%% @doc Creates an abstract function definition. If `Clauses' +%% is `[C1, ..., Cn]', the result represents %% "Name C1; ...; Name -%% Cn.". More exactly, if each Ci +%% Cn.". More exactly, if each `Ci' %% represents "(Pi1, ..., Pim) Gi -> %% Bi", then the result represents %% "Name(P11, ..., P1m) G1 -> @@ -3349,7 +3312,7 @@ revert_function(Node) -> %% ===================================================================== -%% @doc Returns the name subtree of a function node. +%% @doc Returns the name subtree of a `function' node. %% %% @see function/2 @@ -3365,8 +3328,7 @@ function_name(Node) -> %% ===================================================================== -%% @doc Returns the list of clause subtrees of a function -%% node. +%% @doc Returns the list of clause subtrees of a `function' node. %% %% @see function/2 @@ -3382,14 +3344,14 @@ function_clauses(Node) -> %% ===================================================================== -%% @doc Returns the arity of a function node. The result +%% @doc Returns the arity of a `function' node. The result %% is the number of parameter patterns in the first clause of the %% function; subsequent clauses are ignored. %% -%%

An exception is thrown if function_clauses(Node) +%% An exception is thrown if `function_clauses(Node)' %% returns an empty list, or if the first element of that list is not -%% a syntax tree C of type clause such that -%% clause_patterns(C) is a nonempty list.

+%% a syntax tree `C' of type `clause' such that +%% `clause_patterns(C)' is a nonempty list. %% %% @see function/2 %% @see function_clauses/1 @@ -3416,29 +3378,28 @@ clause(Guard, Body) -> %% ===================================================================== -%% @doc Creates an abstract clause. If Patterns is -%% [P1, ..., Pn] and Body is [B1, ..., -%% Bm], then if Guard is none, the +%% @doc Creates an abstract clause. If `Patterns' is +%% `[P1, ..., Pn]' and `Body' is `[B1, ..., +%% Bm]', then if `Guard' is `none', the %% result represents "(P1, ..., Pn) -> %% B1, ..., Bm", otherwise, unless -%% Guard is a list, the result represents +%% `Guard' is a list, the result represents %% "(P1, ..., Pn) when Guard -> %% B1, ..., Bm". %% -%%

For simplicity, the Guard argument may also be any +%% For simplicity, the `Guard' argument may also be any %% of the following: %%

-%%

%% %% @see clause/2 %% @see clause_patterns/1 @@ -3554,8 +3515,7 @@ unfold_try_clause({clause, Pos, [{tuple, _, [C, V, _]}], %% ===================================================================== -%% @doc Returns the list of pattern subtrees of a clause -%% node. +%% @doc Returns the list of pattern subtrees of a `clause' node. %% %% @see clause/3 @@ -3571,11 +3531,11 @@ clause_patterns(Node) -> %% ===================================================================== -%% @doc Returns the guard subtree of a clause node, if -%% any. If Node represents "(P1, ..., +%% @doc Returns the guard subtree of a `clause' node, if +%% any. If `Node' represents "(P1, ..., %% Pn) when Guard -> B1, ..., -%% Bm", Guard is returned. Otherwise, the -%% result is none. +%% Bm", `Guard' is returned. Otherwise, the +%% result is `none'. %% %% @see clause/3 @@ -3597,8 +3557,7 @@ clause_guard(Node) -> %% ===================================================================== -%% @doc Return the list of body subtrees of a clause -%% node. +%% @doc Return the list of body subtrees of a `clause' node. %% %% @see clause/3 @@ -3614,8 +3573,8 @@ clause_body(Node) -> %% ===================================================================== -%% @doc Creates an abstract disjunction. If List is -%% [E1, ..., En], the result represents +%% @doc Creates an abstract disjunction. If `List' is +%% `[E1, ..., En]', the result represents %% "E1; ...; En". %% %% @see disjunction_body/1 @@ -3632,7 +3591,7 @@ disjunction(Tests) -> %% ===================================================================== %% @doc Returns the list of body subtrees of a -%% disjunction node. +%% `disjunction' node. %% %% @see disjunction/1 @@ -3643,8 +3602,8 @@ disjunction_body(Node) -> %% ===================================================================== -%% @doc Creates an abstract conjunction. If List is -%% [E1, ..., En], the result represents +%% @doc Creates an abstract conjunction. If `List' is +%% `[E1, ..., En]', the result represents %% "E1, ..., En". %% %% @see conjunction_body/1 @@ -3661,7 +3620,7 @@ conjunction(Tests) -> %% ===================================================================== %% @doc Returns the list of body subtrees of a -%% conjunction node. +%% `conjunction' node. %% %% @see conjunction/1 @@ -3698,7 +3657,7 @@ revert_catch_expr(Node) -> %% ===================================================================== -%% @doc Returns the body subtree of a catch_expr node. +%% @doc Returns the body subtree of a `catch_expr' node. %% %% @see catch_expr/1 @@ -3746,7 +3705,7 @@ revert_match_expr(Node) -> %% ===================================================================== -%% @doc Returns the pattern subtree of a match_expr node. +%% @doc Returns the pattern subtree of a `match_expr' node. %% %% @see match_expr/2 @@ -3762,7 +3721,7 @@ match_expr_pattern(Node) -> %% ===================================================================== -%% @doc Returns the body subtree of a match_expr node. +%% @doc Returns the body subtree of a `match_expr' node. %% %% @see match_expr/2 @@ -3779,11 +3738,11 @@ match_expr_body(Node) -> %% ===================================================================== %% @doc Creates an abstract operator. The name of the operator is the -%% character sequence represented by Name. This is +%% character sequence represented by `Name'. This is %% analogous to the print name of an atom, but an operator is never %% written within single-quotes; e.g., the result of -%% operator('++') represents "++" rather -%% than "'++'". +%% `operator('++')' represents "`++'" rather +%% than "`'++''". %% %% @see operator_name/1 %% @see operator_literal/1 @@ -3801,7 +3760,7 @@ operator(Name) -> %% ===================================================================== -%% @doc Returns the name of an operator node. Note that +%% @doc Returns the name of an `operator' node. Note that %% the name is returned as an atom. %% %% @see operator/1 @@ -3814,8 +3773,7 @@ operator_name(Node) -> %% ===================================================================== %% @doc Returns the literal string represented by an -%% operator node. This is simply the operator name as a -%% string. +%% `operator' node. This is simply the operator name as a string. %% %% @see operator/1 @@ -3875,7 +3833,7 @@ revert_infix_expr(Node) -> %% ===================================================================== %% @doc Returns the left argument subtree of an -%% infix_expr node. +%% `infix_expr' node. %% %% @see infix_expr/3 @@ -3891,8 +3849,7 @@ infix_expr_left(Node) -> %% ===================================================================== -%% @doc Returns the operator subtree of an infix_expr -%% node. +%% @doc Returns the operator subtree of an `infix_expr' node. %% %% @see infix_expr/3 @@ -3909,7 +3866,7 @@ infix_expr_operator(Node) -> %% ===================================================================== %% @doc Returns the right argument subtree of an -%% infix_expr node. +%% `infix_expr' node. %% %% @see infix_expr/3 @@ -3968,8 +3925,7 @@ revert_prefix_expr(Node) -> %% ===================================================================== -%% @doc Returns the operator subtree of a prefix_expr -%% node. +%% @doc Returns the operator subtree of a `prefix_expr' node. %% %% @see prefix_expr/2 @@ -3985,8 +3941,7 @@ prefix_expr_operator(Node) -> %% ===================================================================== -%% @doc Returns the argument subtree of a prefix_expr -%% node. +%% @doc Returns the argument subtree of a `prefix_expr' node. %% %% @see prefix_expr/2 @@ -4012,7 +3967,7 @@ record_field(Name) -> %% ===================================================================== %% @doc Creates an abstract record field specification. If -%% Value is none, the result represents +%% `Value' is `none', the result represents %% simply "Name", otherwise it represents %% "Name = Value". %% @@ -4034,7 +3989,7 @@ record_field(Name, Value) -> %% ===================================================================== -%% @doc Returns the name subtree of a record_field node. +%% @doc Returns the name subtree of a `record_field' node. %% %% @see record_field/2 @@ -4045,11 +4000,11 @@ record_field_name(Node) -> %% ===================================================================== -%% @doc Returns the value subtree of a record_field node, -%% if any. If Node represents -%% "Name", none is -%% returned. Otherwise, if Node represents -%% "Name = Value", Value +%% @doc Returns the value subtree of a `record_field' node, +%% if any. If `Node' represents +%% "Name", `none' is +%% returned. Otherwise, if `Node' represents +%% "Name = Value", `Value' %% is returned. %% %% @see record_field/2 @@ -4064,9 +4019,9 @@ record_field_value(Node) -> %% @doc Creates an abstract record field index expression. The result %% represents "#Type.Field". %% -%%

(Note: the function name record_index/2 is reserved +%% (Note: the function name `record_index/2' is reserved %% by the Erlang compiler, which is why that name could not be used -%% for this constructor.)

+%% for this constructor.) %% %% @see record_index_expr_type/1 %% @see record_index_expr_field/1 @@ -4105,8 +4060,7 @@ revert_record_index_expr(Node) -> %% ===================================================================== -%% @doc Returns the type subtree of a record_index_expr -%% node. +%% @doc Returns the type subtree of a `record_index_expr' node. %% %% @see record_index_expr/2 @@ -4122,8 +4076,7 @@ record_index_expr_type(Node) -> %% ===================================================================== -%% @doc Returns the field subtree of a record_index_expr -%% node. +%% @doc Returns the field subtree of a `record_index_expr' node. %% %% @see record_index_expr/2 @@ -4149,12 +4102,12 @@ record_access(Argument, Field) -> %% ===================================================================== %% @doc Creates an abstract record field access expression. If -%% Type is not none, the result represents +%% `Type' is not `none', the result represents %% "Argument#Type.Field". %% -%%

If Type is none, the result represents +%% If `Type' is `none', the result represents %% "Argument.Field". This is a special -%% form only allowed within Mnemosyne queries.

+%% form only allowed within Mnemosyne queries. %% %% @see record_access/2 %% @see record_access_argument/1 @@ -4209,8 +4162,7 @@ revert_record_access(Node) -> %% ===================================================================== -%% @doc Returns the argument subtree of a record_access -%% node. +%% @doc Returns the argument subtree of a `record_access' node. %% %% @see record_access/3 @@ -4228,12 +4180,12 @@ record_access_argument(Node) -> %% ===================================================================== -%% @doc Returns the type subtree of a record_access node, -%% if any. If Node represents -%% "Argument.Field", none -%% is returned, otherwise if Node represents +%% @doc Returns the type subtree of a `record_access' node, +%% if any. If `Node' represents +%% "Argument.Field", `none' +%% is returned, otherwise if `Node' represents %% "Argument#Type.Field", -%% Type is returned. +%% `Type' is returned. %% %% @see record_access/3 @@ -4251,8 +4203,7 @@ record_access_type(Node) -> %% ===================================================================== -%% @doc Returns the field subtree of a record_access -%% node. +%% @doc Returns the field subtree of a `record_access' node. %% %% @see record_access/3 @@ -4279,9 +4230,9 @@ record_expr(Type, Fields) -> %% ===================================================================== -%% @doc Creates an abstract record expression. If Fields is -%% [F1, ..., Fn], then if Argument is -%% none, the result represents +%% @doc Creates an abstract record expression. If `Fields' is +%% `[F1, ..., Fn]', then if `Argument' is +%% `none', the result represents %% "#Type{F1, ..., Fn}", %% otherwise it represents %% "Argument#Type{F1, ..., @@ -4347,12 +4298,12 @@ revert_record_expr(Node) -> %% ===================================================================== -%% @doc Returns the argument subtree of a record_expr node, -%% if any. If Node represents -%% "#Type{...}", none is returned. -%% Otherwise, if Node represents +%% @doc Returns the argument subtree of a `record_expr' node, +%% if any. If `Node' represents +%% "#Type{...}", `none' is returned. +%% Otherwise, if `Node' represents %% "Argument#Type{...}", -%% Argument is returned. +%% `Argument' is returned. %% %% @see record_expr/3 @@ -4370,7 +4321,7 @@ record_expr_argument(Node) -> %% ===================================================================== -%% @doc Returns the type subtree of a record_expr node. +%% @doc Returns the type subtree of a `record_expr' node. %% %% @see record_expr/3 @@ -4389,7 +4340,7 @@ record_expr_type(Node) -> %% ===================================================================== %% @doc Returns the list of field subtrees of a -%% record_expr node. +%% `record_expr' node. %% %% @see record_expr/3 @@ -4408,10 +4359,10 @@ record_expr_fields(Node) -> %% ===================================================================== %% @doc Creates an abstract function application expression. If -%% Module is none, this is call is equivalent -%% to application(Function, Arguments), otherwise it is -%% equivalent to application(module_qualifier(Module, Function), -%% Arguments). +%% `Module' is `none', this is call is equivalent +%% to `application(Function, Arguments)', otherwise it is +%% equivalent to `application(module_qualifier(Module, Function), +%% Arguments)'. %% %% (This is a utility function.) %% @@ -4429,7 +4380,7 @@ application(Module, Name, Arguments) -> %% ===================================================================== %% @doc Creates an abstract function application expression. If -%% Arguments is [A1, ..., An], the result +%% `Arguments' is `[A1, ..., An]', the result %% represents "Operator(A1, ..., %% An)". %% @@ -4467,12 +4418,11 @@ revert_application(Node) -> %% ===================================================================== -%% @doc Returns the operator subtree of an application -%% node. +%% @doc Returns the operator subtree of an `application' node. %% -%%

Note: if Node represents +%% Note: if `Node' represents %% "M:F(...)", then the result is the -%% subtree representing "M:F".

+%% subtree representing "M:F". %% %% @see application/2 %% @see module_qualifier/2 @@ -4490,7 +4440,7 @@ application_operator(Node) -> %% ===================================================================== %% @doc Returns the list of argument subtrees of an -%% application node. +%% `application' node. %% %% @see application/2 @@ -4506,8 +4456,8 @@ application_arguments(Node) -> %% ===================================================================== -%% @doc Creates an abstract list comprehension. If Body is -%% [E1, ..., En], the result represents +%% @doc Creates an abstract list comprehension. If `Body' is +%% `[E1, ..., En]', the result represents %% "[Template || E1, ..., En]". %% %% @see list_comp_template/1 @@ -4542,7 +4492,7 @@ revert_list_comp(Node) -> %% ===================================================================== -%% @doc Returns the template subtree of a list_comp node. +%% @doc Returns the template subtree of a `list_comp' node. %% %% @see list_comp/2 @@ -4558,8 +4508,7 @@ list_comp_template(Node) -> %% ===================================================================== -%% @doc Returns the list of body subtrees of a list_comp -%% node. +%% @doc Returns the list of body subtrees of a `list_comp' node. %% %% @see list_comp/2 @@ -4574,8 +4523,8 @@ list_comp_body(Node) -> end. %% ===================================================================== -%% @doc Creates an abstract binary comprehension. If Body is -%% [E1, ..., En], the result represents +%% @doc Creates an abstract binary comprehension. If `Body' is +%% `[E1, ..., En]', the result represents %% "<<Template || E1, ..., En>>". %% %% @see binary_comp_template/1 @@ -4610,7 +4559,7 @@ revert_binary_comp(Node) -> %% ===================================================================== -%% @doc Returns the template subtree of a binary_comp node. +%% @doc Returns the template subtree of a `binary_comp' node. %% %% @see binary_comp/2 @@ -4626,8 +4575,7 @@ binary_comp_template(Node) -> %% ===================================================================== -%% @doc Returns the list of body subtrees of a binary_comp -%% node. +%% @doc Returns the list of body subtrees of a `binary_comp' node. %% %% @see binary_comp/2 @@ -4671,7 +4619,7 @@ revert_query_expr(Node) -> %% ===================================================================== -%% @doc Returns the body subtree of a query_expr node. +%% @doc Returns the body subtree of a `query_expr' node. %% %% @see query_expr/1 @@ -4687,10 +4635,10 @@ query_expr_body(Node) -> %% ===================================================================== -%% @doc Creates an abstract Mnemosyne rule. If Clauses is -%% [C1, ..., Cn], the results represents +%% @doc Creates an abstract Mnemosyne rule. If `Clauses' is +%% `[C1, ..., Cn]', the results represents %% "Name C1; ...; Name -%% Cn.". More exactly, if each Ci +%% Cn.". More exactly, if each `Ci' %% represents "(Pi1, ..., Pim) Gi -> %% Bi", then the result represents %% "Name(P11, ..., P1m) G1 :- @@ -4745,7 +4693,7 @@ revert_rule(Node) -> %% ===================================================================== -%% @doc Returns the name subtree of a rule node. +%% @doc Returns the name subtree of a `rule' node. %% %% @see rule/2 @@ -4760,7 +4708,7 @@ rule_name(Node) -> end. %% ===================================================================== -%% @doc Returns the list of clause subtrees of a rule node. +%% @doc Returns the list of clause subtrees of a `rule' node. %% %% @see rule/2 @@ -4775,14 +4723,14 @@ rule_clauses(Node) -> end. %% ===================================================================== -%% @doc Returns the arity of a rule node. The result is the +%% @doc Returns the arity of a `rule' node. The result is the %% number of parameter patterns in the first clause of the rule; %% subsequent clauses are ignored. %% -%%

An exception is thrown if rule_clauses(Node) returns +%% An exception is thrown if `rule_clauses(Node)' returns %% an empty list, or if the first element of that list is not a syntax -%% tree C of type clause such that -%% clause_patterns(C) is a nonempty list.

+%% tree `C' of type `clause' such that +%% `clause_patterns(C)' is a nonempty list. %% %% @see rule/2 %% @see rule_clauses/1 @@ -4832,7 +4780,7 @@ revert_generator(Node) -> %% ===================================================================== -%% @doc Returns the pattern subtree of a generator node. +%% @doc Returns the pattern subtree of a `generator' node. %% %% @see generator/2 @@ -4848,7 +4796,7 @@ generator_pattern(Node) -> %% ===================================================================== -%% @doc Returns the body subtree of a generator node. +%% @doc Returns the body subtree of a `generator' node. %% %% @see generator/2 @@ -4898,7 +4846,7 @@ revert_binary_generator(Node) -> %% ===================================================================== -%% @doc Returns the pattern subtree of a generator node. +%% @doc Returns the pattern subtree of a `generator' node. %% %% @see binary_generator/2 @@ -4914,7 +4862,7 @@ binary_generator_pattern(Node) -> %% ===================================================================== -%% @doc Returns the body subtree of a generator node. +%% @doc Returns the body subtree of a `generator' node. %% %% @see binary_generator/2 @@ -4930,8 +4878,8 @@ binary_generator_body(Node) -> %% ===================================================================== -%% @doc Creates an abstract block expression. If Body is -%% [B1, ..., Bn], the result represents "begin +%% @doc Creates an abstract block expression. If `Body' is +%% `[B1, ..., Bn]', the result represents "begin %% B1, ..., Bn end". %% %% @see block_expr_body/1 @@ -4959,8 +4907,7 @@ revert_block_expr(Node) -> %% ===================================================================== -%% @doc Returns the list of body subtrees of a block_expr -%% node. +%% @doc Returns the list of body subtrees of a `block_expr' node. %% %% @see block_expr/1 @@ -4976,10 +4923,10 @@ block_expr_body(Node) -> %% ===================================================================== -%% @doc Creates an abstract if-expression. If Clauses is -%% [C1, ..., Cn], the result represents "if +%% @doc Creates an abstract if-expression. If `Clauses' is +%% `[C1, ..., Cn]', the result represents "if %% C1; ...; Cn end". More exactly, if each -%% Ci represents "() Gi -> +%% `Ci' represents "() Gi -> %% Bi", then the result represents "if %% G1 -> B1; ...; Gn -> Bn %% end". @@ -5014,8 +4961,7 @@ revert_if_expr(Node) -> %% ===================================================================== -%% @doc Returns the list of clause subtrees of an if_expr -%% node. +%% @doc Returns the list of clause subtrees of an `if_expr' node. %% %% @see if_expr/1 @@ -5031,10 +4977,10 @@ if_expr_clauses(Node) -> %% ===================================================================== -%% @doc Creates an abstract case-expression. If Clauses is -%% [C1, ..., Cn], the result represents "case +%% @doc Creates an abstract case-expression. If `Clauses' is +%% `[C1, ..., Cn]', the result represents "case %% Argument of C1; ...; Cn end". More -%% exactly, if each Ci represents "(Pi) +%% exactly, if each `Ci' represents "(Pi) %% Gi -> Bi", then the result represents %% "case Argument of P1 G1 -> %% B1; ...; Pn Gn -> Bn end". @@ -5078,7 +5024,7 @@ revert_case_expr(Node) -> %% ===================================================================== -%% @doc Returns the argument subtree of a case_expr node. +%% @doc Returns the argument subtree of a `case_expr' node. %% %% @see case_expr/2 @@ -5094,8 +5040,7 @@ case_expr_argument(Node) -> %% ===================================================================== -%% @doc Returns the list of clause subtrees of a case_expr -%% node. +%% @doc Returns the list of clause subtrees of a `case_expr' node. %% %% @see case_expr/2 @@ -5111,10 +5056,10 @@ case_expr_clauses(Node) -> %% ===================================================================== -%% @doc Creates an abstract cond-expression. If Clauses is -%% [C1, ..., Cn], the result represents "cond +%% @doc Creates an abstract cond-expression. If `Clauses' is +%% `[C1, ..., Cn]', the result represents "cond %% C1; ...; Cn end". More exactly, if each -%% Ci represents "() Ei -> +%% `Ci' represents "() Ei -> %% Bi", then the result represents "cond %% E1 -> B1; ...; En -> Bn %% end". @@ -5149,8 +5094,7 @@ revert_cond_expr(Node) -> %% ===================================================================== -%% @doc Returns the list of clause subtrees of a cond_expr -%% node. +%% @doc Returns the list of clause subtrees of a `cond_expr' node. %% %% @see cond_expr/1 @@ -5175,21 +5119,21 @@ receive_expr(Clauses) -> %% ===================================================================== -%% @doc Creates an abstract receive-expression. If Timeout -%% is none, the result represents "receive -%% C1; ...; Cn end" (the Action -%% argument is ignored). Otherwise, if Clauses is -%% [C1, ..., Cn] and Action is [A1, ..., -%% Am], the result represents "receive C1; ...; +%% @doc Creates an abstract receive-expression. If `Timeout' +%% is `none', the result represents "receive +%% C1; ...; Cn end" (the `Action' +%% argument is ignored). Otherwise, if `Clauses' is +%% `[C1, ..., Cn]' and `Action' is `[A1, ..., +%% Am]', the result represents "receive C1; ...; %% Cn after Timeout -> A1, ..., Am -%% end". More exactly, if each Ci represents +%% end". More exactly, if each `Ci' represents %% "(Pi) Gi -> Bi", then the %% result represents "receive P1 G1 -> %% B1; ...; Pn Gn -> Bn ... %% end". %% -%%

Note that in Erlang, a receive-expression must have at least one -%% clause if no timeout part is specified.

+%% Note that in Erlang, a receive-expression must have at least one +%% clause if no timeout part is specified. %% %% @see receive_expr_clauses/1 %% @see receive_expr_timeout/1 @@ -5254,7 +5198,7 @@ revert_receive_expr(Node) -> %% ===================================================================== %% @doc Returns the list of clause subtrees of a -%% receive_expr node. +%% `receive_expr' node. %% %% @see receive_expr/3 @@ -5272,12 +5216,12 @@ receive_expr_clauses(Node) -> %% ===================================================================== -%% @doc Returns the timeout subtree of a receive_expr node, -%% if any. If Node represents "receive C1; -%% ...; Cn end", none is returned. -%% Otherwise, if Node represents "receive +%% @doc Returns the timeout subtree of a `receive_expr' node, +%% if any. If `Node' represents "receive C1; +%% ...; Cn end", `none' is returned. +%% Otherwise, if `Node' represents "receive %% C1; ...; Cn after Timeout -> ... end", -%% Timeout is returned. +%% `Timeout' is returned. %% %% @see receive_expr/3 @@ -5296,7 +5240,7 @@ receive_expr_timeout(Node) -> %% ===================================================================== %% @doc Returns the list of action body subtrees of a -%% receive_expr node. If Node represents +%% `receive_expr' node. If `Node' represents %% "receive C1; ...; Cn end", this is the %% empty list. %% @@ -5343,26 +5287,26 @@ try_after_expr(Body, After) -> %% ===================================================================== -%% @doc Creates an abstract try-expression. If Body is -%% [B1, ..., Bn], Clauses is [C1, ..., -%% Cj], Handlers is [H1, ..., Hk], and -%% After is [A1, ..., Am], the result +%% @doc Creates an abstract try-expression. If `Body' is +%% `[B1, ..., Bn]', `Clauses' is `[C1, ..., +%% Cj]', `Handlers' is `[H1, ..., Hk]', and +%% `After' is `[A1, ..., Am]', the result %% represents "try B1, ..., Bn of C1; %% ...; Cj catch H1; ...; Hk after %% A1, ..., Am end". More exactly, if each -%% Ci represents "(CPi) CGi -> -%% CBi", and each Hi represents +%% `Ci' represents "(CPi) CGi -> +%% CBi", and each `Hi' represents %% "(HPi) HGi -> HBi", then the %% result represents "try B1, ..., Bn of %% CP1 CG1 -> CB1; ...; CPj %% CGj -> CBj catch HP1 HG1 -> %% HB1; ...; HPk HGk -> HBk after -%% A1, ..., Am end"; cf. -%% case_expr/2. If Clauses is the empty list, -%% the of ... section is left out. If After is -%% the empty list, the after ... section is left out. If -%% Handlers is the empty list, and After is -%% nonempty, the catch ... section is left out. +%% A1, ..., Am end"; see +%% {@link case_expr/2}. If `Clauses' is the empty list, +%% the `of ...' section is left out. If `After' is +%% the empty list, the `after ...' section is left out. If +%% `Handlers' is the empty list, and `After' is +%% nonempty, the `catch ...' section is left out. %% %% @see try_expr_body/1 %% @see try_expr_clauses/1 @@ -5420,8 +5364,7 @@ revert_try_expr(Node) -> %% ===================================================================== -%% @doc Returns the list of body subtrees of a try_expr -%% node. +%% @doc Returns the list of body subtrees of a `try_expr' node. %% %% @see try_expr/4 @@ -5438,7 +5381,7 @@ try_expr_body(Node) -> %% ===================================================================== %% @doc Returns the list of case-clause subtrees of a -%% try_expr node. If Node represents +%% `try_expr' node. If `Node' represents %% "try Body catch H1; ...; Hn %% end", the result is the empty list. %% @@ -5457,7 +5400,7 @@ try_expr_clauses(Node) -> %% ===================================================================== %% @doc Returns the list of handler-clause subtrees of a -%% try_expr node. +%% `try_expr' node. %% %% @see try_expr/4 @@ -5473,8 +5416,7 @@ try_expr_handlers(Node) -> %% ===================================================================== -%% @doc Returns the list of "after" subtrees of a try_expr -%% node. +%% @doc Returns the list of "after" subtrees of a `try_expr' node. %% %% @see try_expr/4 @@ -5513,7 +5455,7 @@ class_qualifier(Class, Body) -> %% ===================================================================== %% @doc Returns the argument (the class) subtree of a -%% class_qualifier node. +%% `class_qualifier' node. %% %% @see class_qualifier/2 @@ -5524,7 +5466,7 @@ class_qualifier_argument(Node) -> %% ===================================================================== -%% @doc Returns the body subtree of a class_qualifier node. +%% @doc Returns the body subtree of a `class_qualifier' node. %% %% @see class_qualifier/2 @@ -5536,9 +5478,9 @@ class_qualifier_body(Node) -> %% ===================================================================== %% @doc Creates an abstract "implicit fun" expression. If -%% Arity is none, this is equivalent to -%% implicit_fun(Name), otherwise it is equivalent to -%% implicit_fun(arity_qualifier(Name, Arity)). +%% `Arity' is `none', this is equivalent to +%% `implicit_fun(Name)', otherwise it is equivalent to +%% `implicit_fun(arity_qualifier(Name, Arity))'. %% %% (This is a utility function.) %% @@ -5555,10 +5497,10 @@ implicit_fun(Name, Arity) -> %% ===================================================================== %% @doc Creates an abstract module-qualified "implicit fun" expression. -%% If Module is none, this is equivalent to -%% implicit_fun(Name, Arity), otherwise it is equivalent to -%% implicit_fun(module_qualifier(Module, arity_qualifier(Name, -%% Arity)). +%% If `Module' is `none', this is equivalent to +%% `implicit_fun(Name, Arity)', otherwise it is equivalent to +%% `implicit_fun(module_qualifier(Module, arity_qualifier(Name, +%% Arity))'. %% %% (This is a utility function.) %% @@ -5576,7 +5518,7 @@ implicit_fun(Module, Name, Arity) -> %% ===================================================================== %% @doc Creates an abstract "implicit fun" expression. The result -%% represents "fun Name". Name should +%% represents "fun Name". `Name' should %% represent either F/A or %% M:F/A %% @@ -5635,13 +5577,13 @@ revert_implicit_fun(Node) -> %% ===================================================================== -%% @doc Returns the name subtree of an implicit_fun node. +%% @doc Returns the name subtree of an `implicit_fun' node. %% -%%

Note: if Node represents "fun +%% Note: if `Node' represents "fun %% N/A" or "fun %% M:N/A", then the result is the %% subtree representing "N/A" or -%% "M:N/A", respectively.

+%% "M:N/A", respectively. %% %% @see implicit_fun/1 %% @see arity_qualifier/2 @@ -5671,10 +5613,10 @@ implicit_fun_name(Node) -> %% ===================================================================== -%% @doc Creates an abstract fun-expression. If Clauses is -%% [C1, ..., Cn], the result represents "fun +%% @doc Creates an abstract fun-expression. If `Clauses' is +%% `[C1, ..., Cn]', the result represents "fun %% C1; ...; Cn end". More exactly, if each -%% Ci represents "(Pi1, ..., Pim) +%% `Ci' represents "(Pi1, ..., Pim) %% Gi -> Bi", then the result represents %% "fun (P11, ..., P1m) G1 -> %% B1; ...; (Pn1, ..., Pnm) Gn -> @@ -5711,8 +5653,7 @@ revert_fun_expr(Node) -> %% ===================================================================== -%% @doc Returns the list of clause subtrees of a fun_expr -%% node. +%% @doc Returns the list of clause subtrees of a `fun_expr' node. %% %% @see fun_expr/1 @@ -5728,14 +5669,14 @@ fun_expr_clauses(Node) -> %% ===================================================================== -%% @doc Returns the arity of a fun_expr node. The result is +%% @doc Returns the arity of a `fun_expr' node. The result is %% the number of parameter patterns in the first clause of the %% fun-expression; subsequent clauses are ignored. %% -%%

An exception is thrown if fun_expr_clauses(Node) +%% An exception is thrown if `fun_expr_clauses(Node)' %% returns an empty list, or if the first element of that list is not a -%% syntax tree C of type clause such that -%% clause_patterns(C) is a nonempty list.

+%% syntax tree `C' of type `clause' such that +%% `clause_patterns(C)' is a nonempty list. %% %% @see fun_expr/1 %% @see fun_expr_clauses/1 @@ -5768,7 +5709,7 @@ revert_parentheses(Node) -> %% ===================================================================== -%% @doc Returns the body subtree of a parentheses node. +%% @doc Returns the body subtree of a `parentheses' node. %% %% @see parentheses/1 @@ -5788,22 +5729,22 @@ macro(Name) -> %% ===================================================================== -%% @doc Creates an abstract macro application. If Arguments -%% is none, the result represents -%% "?Name", otherwise, if Arguments -%% is [A1, ..., An], the result represents +%% @doc Creates an abstract macro application. If `Arguments' +%% is `none', the result represents +%% "?Name", otherwise, if `Arguments' +%% is `[A1, ..., An]', the result represents %% "?Name(A1, ..., An)". %% -%%

Notes: if Arguments is the empty list, the result +%% Notes: if `Arguments' is the empty list, the result %% will thus represent "?Name()", including a pair -%% of matching parentheses.

+%% of matching parentheses. %% -%%

The only syntactical limitation imposed by the preprocessor on the +%% The only syntactical limitation imposed by the preprocessor on the %% arguments to a macro application (viewed as sequences of tokens) is %% that they must be balanced with respect to parentheses, brackets, -%% begin ... end, case ... end, etc. The -%% text node type can be used to represent arguments which -%% are not regular Erlang constructs.

+%% `begin ... end', `case ... end', etc. The +%% `text' node type can be used to represent arguments which +%% are not regular Erlang constructs. %% %% @see macro_name/1 %% @see macro_arguments/1 @@ -5825,7 +5766,7 @@ macro(Name, Arguments) -> %% ===================================================================== -%% @doc Returns the name subtree of a macro node. +%% @doc Returns the name subtree of a `macro' node. %% %% @see macro/2 @@ -5836,12 +5777,12 @@ macro_name(Node) -> %% ===================================================================== -%% @doc Returns the list of argument subtrees of a macro -%% node, if any. If Node represents -%% "?Name", none is returned. -%% Otherwise, if Node represents +%% @doc Returns the list of argument subtrees of a `macro' +%% node, if any. If `Node' represents +%% "?Name", `none' is returned. +%% Otherwise, if `Node' represents %% "?Name(A1, ..., An)", -%% [A1, ..., An] is returned. +%% `[A1, ..., An]' is returned. %% %% @see macro/2 @@ -5853,12 +5794,12 @@ macro_arguments(Node) -> %% ===================================================================== %% @doc Returns the syntax tree corresponding to an Erlang term. -%% Term must be a literal term, i.e., one that can be +%% `Term' must be a literal term, i.e., one that can be %% represented as a source code literal. Thus, it may not contain a %% process identifier, port, reference, binary or function value as a %% subterm. The function recognises printable strings, in order to get a %% compact and readable representation. Evaluation fails with reason -%% badarg if Term is not a literal term. +%% `badarg' if `Term' is not a literal term. %% %% @see concrete/1 %% @see is_literal/1 @@ -5909,16 +5850,16 @@ abstract_tail(H, T) -> %% ===================================================================== %% @doc Returns the Erlang term represented by a syntax tree. Evaluation -%% fails with reason badarg if Node does not +%% fails with reason `badarg' if `Node' does not %% represent a literal term. %% -%%

Note: Currently, the set of syntax trees which have a concrete +%% Note: Currently, the set of syntax trees which have a concrete %% representation is larger than the set of trees which can be built -%% using the function abstract/1. An abstract character -%% will be concretised as an integer, while abstract/1 does +%% using the function {@link abstract/1}. An abstract character +%% will be concretised as an integer, while {@link abstract/1} does %% not at present yield an abstract character for any input. (Use the -%% char/1 function to explicitly create an abstract -%% character.)

+%% {@link char/1} function to explicitly create an abstract +%% character.) %% %% @see abstract/1 %% @see is_literal/1 @@ -5961,7 +5902,7 @@ concrete(Node) -> {value, concrete(F), []} end, [], true), B; - _ -> + _ -> erlang:error({badarg, Node}) end. @@ -5972,10 +5913,10 @@ concrete_list([]) -> %% ===================================================================== -%% @doc Returns true if Node represents a -%% literal term, otherwise false. This function returns -%% true if and only if the value of -%% concrete(Node) is defined. +%% @doc Returns `true' if `Node' represents a +%% literal term, otherwise `false'. This function returns +%% `true' if and only if the value of +%% `concrete(Node)' is defined. %% %% @see abstract/1 %% @see concrete/1 @@ -6006,19 +5947,19 @@ is_literal(T) -> %% ===================================================================== -%% @doc Returns an erl_parse-compatible representation of a -%% syntax tree, if possible. If Tree represents a +%% @doc Returns an `erl_parse'-compatible representation of a +%% syntax tree, if possible. If `Tree' represents a %% well-formed Erlang program or expression, the conversion should work -%% without problems. Typically, is_tree/1 yields -%% true if conversion failed (i.e., the result is still an -%% abstract syntax tree), and false otherwise. +%% without problems. Typically, {@link is_tree/1} yields +%% `true' if conversion failed (i.e., the result is still an +%% abstract syntax tree), and `false' otherwise. %% -%%

The is_tree/1 test is not completely foolproof. For a -%% few special node types (e.g. arity_qualifier), if such a +%% The {@link is_tree/1} test is not completely foolproof. For a +%% few special node types (e.g. `arity_qualifier'), if such a %% node occurs in a context where it is not expected, it will be left %% unchanged as a non-reverted subtree of the result. This can only -%% happen if Tree does not actually represent legal Erlang -%% code.

+%% happen if `Tree' does not actually represent legal Erlang +%% code. %% %% @see revert_forms/1 %% @see //stdlib/erl_parse @@ -6155,11 +6096,11 @@ revert_root(Node) -> %% ===================================================================== %% @doc Reverts a sequence of Erlang source code forms. The sequence can -%% be given either as a form_list syntax tree (possibly +%% be given either as a `form_list' syntax tree (possibly %% nested), or as a list of "program form" syntax trees. If successful, -%% the corresponding flat list of erl_parse-compatible -%% syntax trees is returned (cf. revert/1). If some program -%% form could not be reverted, {error, Form} is thrown. +%% the corresponding flat list of `erl_parse'-compatible +%% syntax trees is returned (see {@link revert/1}). If some program +%% form could not be reverted, `{error, Form}' is thrown. %% Standalone comments in the form sequence are discarded. %% %% @see revert/1 @@ -6209,57 +6150,53 @@ revert_forms_1([]) -> %% ===================================================================== %% @doc Returns the grouped list of all subtrees of a syntax tree. If -%% Node is a leaf node (cf. is_leaf/1), this +%% `Node' is a leaf node (see {@link is_leaf/1}), this %% is the empty list, otherwise the result is always a nonempty list, -%% containing the lists of subtrees of Node, in +%% containing the lists of subtrees of `Node', in %% left-to-right order as they occur in the printed program text, and %% grouped by category. Often, each group contains only a single %% subtree. %% -%%

Depending on the type of Node, the size of some +%% Depending on the type of `Node', the size of some %% groups may be variable (e.g., the group consisting of all the %% elements of a tuple), while others always contain the same number of %% elements - usually exactly one (e.g., the group containing the %% argument expression of a case-expression). Note, however, that the %% exact structure of the returned list (for a given node type) should %% in general not be depended upon, since it might be subject to change -%% without notice.

+%% without notice. %% -%%

The function subtrees/1 and the constructor functions -%% make_tree/2 and update_tree/2 can be a +%% The function {@link subtrees/1} and the constructor functions +%% {@link make_tree/2} and {@link update_tree/2} can be a %% great help if one wants to traverse a syntax tree, visiting all its %% subtrees, but treat nodes of the tree in a uniform way in most or all %% cases. Using these functions makes this simple, and also assures that %% your code is not overly sensitive to extensions of the syntax tree %% data type, because any node types not explicitly handled by your code -%% can be left to a default case.

+%% can be left to a default case. %% -%%

For example: -%% 

-%%   postorder(F, Tree) ->
+%% For example:
+%% ```postorder(F, Tree) ->
 %%       F(case subtrees(Tree) of
 %%           [] -> Tree;
 %%           List -> update_tree(Tree,
 %%                               [[postorder(F, Subtree)
 %%                                 || Subtree <- Group]
 %%                                || Group <- List])
-%%         end).
-%%
-%% maps the function F on Tree and all its +%% end).''' +%% maps the function `F' on `Tree' and all its %% subtrees, doing a post-order traversal of the syntax tree. (Note the -%% use of update_tree/2 to preserve node attributes.) For a +%% use of {@link update_tree/2} to preserve node attributes.) For a %% simple function like: -%% 
-%%   f(Node) ->
+%% ```f(Node) ->
 %%       case type(Node) of
 %%           atom -> atom("a_" ++ atom_name(Node));
 %%           _ -> Node
-%%       end.
-%%
-%% the call postorder(fun f/1, Tree) will yield a new -%% representation of Tree in which all atom names have been +%% end.''' +%% the call `postorder(fun f/1, Tree)' will yield a new +%% representation of `Tree' in which all atom names have been %% extended with the prefix "a_", but nothing else (including comments, -%% annotations and line numbers) has been changed.

+%% annotations and line numbers) has been changed. %% %% @see make_tree/2 %% @see type/1 @@ -6430,8 +6367,8 @@ subtrees(T) -> %% ===================================================================== %% @doc Creates a syntax tree with the same type and attributes as the -%% given tree. This is equivalent to copy_attrs(Node, -%% make_tree(type(Node), Groups)). +%% given tree. This is equivalent to `copy_attrs(Node, +%% make_tree(type(Node), Groups))'. %% %% @see make_tree/2 %% @see copy_attrs/2 @@ -6445,19 +6382,19 @@ update_tree(Node, Groups) -> %% ===================================================================== %% @doc Creates a syntax tree with the given type and subtrees. -%% Type must be a node type name (cf. type/1) -%% that does not denote a leaf node type (cf. is_leaf/1). -%% Groups must be a nonempty list of groups of +%% `Type' must be a node type name (see {@link type/1}) +%% that does not denote a leaf node type (see {@link is_leaf/1}). +%% `Groups' must be a nonempty list of groups of %% syntax trees, representing the subtrees of a node of the given type, %% in left-to-right order as they would occur in the printed program -%% text, grouped by category as done by subtrees/1. +%% text, grouped by category as done by {@link subtrees/1}. %% -%%

The result of copy_attrs(Node, make_tree(type(Node), -%% subtrees(Node))) (cf. update_tree/2) represents -%% the same source code text as the original Node, assuming -%% that subtrees(Node) yields a nonempty list. However, it +%% The result of `copy_attrs(Node, make_tree(type(Node), +%% subtrees(Node)))' (see {@link update_tree/2}) represents +%% the same source code text as the original `Node', assuming +%% that `subtrees(Node)' yields a nonempty list. However, it %% does not necessarily have the same data representation as -%% Node.

+%% `Node'. %% %% @see update_tree/2 %% @see subtrees/1 @@ -6525,37 +6462,37 @@ make_tree(tuple, [E]) -> tuple(E). %% @doc Creates a meta-representation of a syntax tree. The result %% represents an Erlang expression "MetaTree" %% which, if evaluated, will yield a new syntax tree representing the -%% same source code text as Tree (although the actual data +%% same source code text as `Tree' (although the actual data %% representation may be different). The expression represented by -%% MetaTree is implementation independent with +%% `MetaTree' is implementation independent with %% regard to the data structures used by the abstract syntax tree -%% implementation. Comments attached to nodes of Tree will +%% implementation. Comments attached to nodes of `Tree' will %% be preserved, but other attributes are lost. %% -%%

Any node in Tree whose node type is -%% variable (cf. type/1), and whose list of -%% annotations (cf. get_ann/1) contains the atom -%% meta_var, will remain unchanged in the resulting tree, -%% except that exactly one occurrence of meta_var is -%% removed from its annotation list.

+%% Any node in `Tree' whose node type is +%% `variable' (see {@link type/1}), and whose list of +%% annotations (see {@link get_ann/1}) contains the atom +%% `meta_var', will remain unchanged in the resulting tree, +%% except that exactly one occurrence of `meta_var' is +%% removed from its annotation list. %% -%%

The main use of the function meta/1 is to transform a -%% data structure Tree, which represents a piece of program +%% The main use of the function `meta/1' is to transform a +%% data structure `Tree', which represents a piece of program %% code, into a form that is representation independent when -%% printed. E.g., suppose Tree represents a variable -%% named "V". Then (assuming a function print/1 for -%% printing syntax trees), evaluating print(abstract(Tree)) -%% - simply using abstract/1 to map the actual data +%% printed. E.g., suppose `Tree' represents a variable +%% named "V". Then (assuming a function `print/1' for +%% printing syntax trees), evaluating `print(abstract(Tree))' +%% - simply using {@link abstract/1} to map the actual data %% structure onto a syntax tree representation - would output a string -%% that might look something like "{tree, variable, ..., "V", -%% ...}", which is obviously dependent on the implementation of +%% that might look something like "`{tree, variable, ..., "V", +%% ...}'", which is obviously dependent on the implementation of %% the abstract syntax trees. This could e.g. be useful for caching a %% syntax tree in a file. However, in some situations like in a program %% generator generator (with two "generator"), it may be unacceptable. -%% Using print(meta(Tree)) instead would output a +%% Using `print(meta(Tree))' instead would output a %% representation independent syntax tree generating %% expression; in the above case, something like -%% "erl_syntax:variable("V")".

+%% "`erl_syntax:variable("V")'". %% %% @see abstract/1 %% @see type/1 @@ -6695,29 +6632,30 @@ tree(Type) -> %% ===================================================================== %% @doc For special purposes only. Creates an abstract syntax -%% tree node with type tag Type and associated data -%% Data. +%% tree node with type tag `Type' and associated data +%% `Data'. %% -%%

This function and the related is_tree/1 and -%% data/1 provide a uniform way to extend the set of -%% erl_parse node types. The associated data is any term, -%% whose format may depend on the type tag.

+%% This function and the related {@link is_tree/1} and +%% {@link data/1} provide a uniform way to extend the set of +%% `erl_parse' node types. The associated data is any term, +%% whose format may depend on the type tag. %% -%%

Notes:

+%% === Notes: === %%
    %%
  • Any nodes created outside of this module must have type tags %% distinct from those currently defined by this module; see -%% type/1 for a complete list.
    • +%% {@link type/1} for a complete list. %%
  • The type tag of a syntax tree node may also be used -%% as a primary tag by the erl_parse representation; +%% as a primary tag by the `erl_parse' representation; %% in that case, the selector functions for that node type %% must handle both the abstract syntax tree and the -%% erl_parse form. The function type(T) +%% `erl_parse' form. The function `type(T)' %% should return the correct type tag regardless of the -%% representation of T, so that the user sees no -%% difference between erl_syntax and -%% erl_parse nodes.
    • +%% representation of `T', so that the user sees no +%% difference between `erl_syntax' and +%% `erl_parse' nodes. %%
+%% %% @see is_tree/1 %% @see data/1 %% @see type/1 @@ -6729,12 +6667,12 @@ tree(Type, Data) -> %% ===================================================================== -%% @doc For special purposes only. Returns true if -%% Tree is an abstract syntax tree and false +%% @doc For special purposes only. Returns `true' if +%% `Tree' is an abstract syntax tree and `false' %% otherwise. %% -%%

Note: this function yields false for all -%% "old-style" erl_parse-compatible "parse trees".

+%% Note: this function yields `false' for all +%% "old-style" `erl_parse'-compatible "parse trees". %% %% @see tree/2 @@ -6749,8 +6687,8 @@ is_tree(_) -> %% ===================================================================== %% @doc For special purposes only. Returns the associated data %% of a syntax tree node. Evaluation fails with reason -%% badarg if is_tree(Node) does not yield -%% true. +%% `badarg' if `is_tree(Node)' does not yield +%% `true'. %% %% @see tree/2 @@ -6766,17 +6704,17 @@ data(T) -> erlang:error({badarg, T}). %% ===================================================================== -%% @doc Creates a wrapper structure around an erl_parse +%% @doc Creates a wrapper structure around an `erl_parse' %% "parse tree". %% -%%

This function and the related unwrap/1 and -%% is_wrapper/1 provide a uniform way to attach arbitrary -%% information to an erl_parse tree. Some information about +%% This function and the related {@link unwrap/1} and +%% {@link is_wrapper/1} provide a uniform way to attach arbitrary +%% information to an `erl_parse' tree. Some information about %% the encapsuled tree may be cached in the wrapper, such as the node %% type. All functions on syntax trees must behave so that the user sees -%% no difference between wrapped and non-wrapped erl_parse +%% no difference between wrapped and non-wrapped `erl_parse' %% trees. Attaching a wrapper onto another wrapper structure is an -%% error.

+%% error. -spec wrap(erl_parse()) -> #wrapper{}. @@ -6787,9 +6725,9 @@ wrap(Node) -> %% ===================================================================== -%% @doc Removes any wrapper structure, if present. If Node +%% @doc Removes any wrapper structure, if present. If `Node' %% is a wrapper structure, this function returns the wrapped -%% erl_parse tree; otherwise it returns Node +%% `erl_parse' tree; otherwise it returns `Node' %% itself. -spec unwrap(syntaxTree()) -> #tree{} | erl_parse(). @@ -6799,8 +6737,8 @@ unwrap(Node) -> Node. % This could also be a new-form node. %% ===================================================================== -%% @doc Returns true if the argument is a wrapper -%% structure, otherwise false. +%% @doc Returns `true' if the argument is a wrapper +%% structure, otherwise `false'. -ifndef(NO_UNUSED). -spec is_wrapper(term()) -> boolean(). -- cgit v1.2.3