Assuming Forms
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 line
-attributes).
If Forms
is a syntax tree of some other type than form_list
, the comments will be inserted directly using recomment_tree/2
, and any comments left over from that process are added as postcomments on the result.
Entries in Comments
represent multi-line comments. For each entry, Line
is the line number and Column
the left column of the comment (the column of the first comment-introducing "%
" character). Indentation
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. Text
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 "%
" and up to (but not including) the terminating newline. (Cf. module erl_comment_scan
.)
Evaluation exits with reason {bad_position, Pos}
if the associated position information Pos
of some subtree in the input does not have a recognizable format, or with reason {bad_tree, L, C}
if insertion of a comment at line L
, column C
, fails because the tree structure is ill-formed.
See also: erl_comment_scan
, quick_recomment_forms/2
, recomment_tree/2
.