.TH erl_recomment 3erl "syntax_tools 3.1" "" "Erlang Module Definition"
.SH NAME
erl_recomment \- Inserting comments into abstract Erlang syntax trees.
.SH DESCRIPTION
.LP
Inserting comments into abstract Erlang syntax trees
.LP
This module contains functions for inserting comments, described by position, indentation and text, as attachments on an abstract syntax tree, at the correct places\&.
.SH "DATA TYPES"

.RS 2
.TP 2
.B
syntaxTree() = erl_syntax:syntaxTree():

.RS 2
.LP
An abstract syntax tree\&. See the erl_syntax module for details\&.
.RE

.RE
.SH EXPORTS
.LP
.B
quick_recomment_forms(Tree::erl_syntax:forms(), Cs::[erl_comment_scan:comment()]) -> erl_syntax:syntaxTree()
.br
.RS
.LP
Like recomment_forms/2, but only inserts top-level comments\&. Comments within function definitions or declarations ("forms") are simply ignored\&.
.RE

.LP
.B
recomment_forms(Tree::erl_syntax:forms(), Cs::[erl_comment_scan:comment()]) -> erl_syntax:syntaxTree()
.br
.RS
.LP
Attaches comments to the syntax tree/trees representing a program\&. The given \fIForms\fR\& should be a single syntax tree of type \fIform_list\fR\&, or a list of syntax trees representing "program forms"\&. The syntax trees must contain valid position information (for details, see \fIrecomment_tree/2\fR\&)\&. The result is a corresponding syntax tree of type \fIform_list\fR\& in which all comments in the list \fIComments\fR\& have been attached at the proper places\&.
.LP
Assuming \fIForms\fR\& represents a program (or any sequence of "program forms"), any comments whose first lines are not directly associated with a specific program form will become standalone comments inserted between the neighbouring program forms\&. Furthermore, comments whose column position is less than or equal to one will not be attached to a program form that begins at a conflicting line number (this can happen with preprocessor-generated \fIline\fR\&-attributes)\&.
.LP
If \fIForms\fR\& is a syntax tree of some other type than \fIform_list\fR\&, the comments will be inserted directly using \fIrecomment_tree/2\fR\&, and any comments left over from that process are added as postcomments on the result\&.
.LP
Entries in \fIComments\fR\& represent multi-line comments\&. For each entry, \fILine\fR\& is the line number and \fIColumn\fR\& the left column of the comment (the column of the first comment-introducing "\fI%\fR\&" character)\&. \fIIndentation\fR\& is the number of character positions between the last non-whitespace character before the comment (or the left margin) and the left column of the comment\&. \fIText\fR\& is a list of strings representing the consecutive comment lines in top-down order, where each string contains all characters following (but not including) the comment-introducing "\fI%\fR\&" and up to (but not including) the terminating newline\&. (Cf\&. module \fIerl_comment_scan\fR\&\&.)
.LP
Evaluation exits with reason \fI{bad_position, Pos}\fR\& if the associated position information \fIPos\fR\& of some subtree in the input does not have a recognizable format, or with reason \fI{bad_tree, L, C}\fR\& if insertion of a comment at line \fIL\fR\&, column \fIC\fR\&, fails because the tree structure is ill-formed\&.
.LP
\fISee also:\fR\& erl_comment_scan, quick_recomment_forms/2, recomment_tree/2\&.
.RE

.LP
.B
recomment_tree(Tree::erl_syntax:syntaxTree(), Cs::[erl_comment_scan:comment()]) -> {erl_syntax:syntaxTree(), [erl_comment_scan:comment()]}
.br
.RS
.LP
Attaches comments to a syntax tree\&. The result is a pair \fI{NewTree, Remainder}\fR\& where \fINewTree\fR\& is the given \fITree\fR\& where comments from the list \fIComments\fR\& have been attached at the proper places\&. \fIRemainder\fR\& is the list of entries in \fIComments\fR\& which have not been inserted, because their line numbers are greater than those of any node in the tree\&. The entries in \fIComments\fR\& are inserted in order; if two comments become attached to the same node, they will appear in the same order in the program text\&.
.LP
The nodes of the syntax tree must contain valid position information\&. This can be single integers, assumed to represent a line number, or 2- or 3-tuples where the first or second element is an integer, in which case the leftmost integer element is assumed to represent the line number\&. Line numbers less than one are ignored (usually, the default line number for newly created nodes is zero)\&.
.LP
For details on the \fILine\fR\&, \fIColumn\fR\& and \fIIndentation\fR\& fields, and the behaviour in case of errors, see \fIrecomment_forms/2\fR\&\&.
.LP
\fISee also:\fR\& recomment_forms/2\&.
.RE

.SH AUTHORS
.LP
Richard Carlsson
.I
<carlsson\&.richard@gmail\&.com>