erl_recomment(3erl)					     Erlang Module Definition					       erl_recomment(3erl)

NAME

       erl_recomment - Inserting comments into abstract Erlang syntax trees.

DESCRIPTION

       Inserting comments into abstract Erlang syntax trees

       This  module  contains  functions for inserting comments, described by position, indentation and text, as attachments on an abstract syntax
       tree, at the correct places.

EXPORTS

       quick_recomment_forms(Tree::Forms, Comments::[Comment]) -> syntaxTree()

	      Types  Forms = syntaxTree() | [syntaxTree()]
		     Comment = {Line, Column, Indentation, Text}
		     Line = integer()
		     Column = integer()
		     Indentation = integer()
		     Text = [string()]

	      Like recomment_forms/2 , but only inserts top-level comments. Comments within function definitions  or  declarations  ("forms")  are
	      simply ignored.

       recomment_forms(Tree::Forms, Comments::[Comment]) -> syntaxTree()

	      Types  syntaxTree() (see module erl_syntax)
		     Forms = syntaxTree() | [syntaxTree()]
		     Comment = {Line, Column, Indentation, Text}
		     Line = integer()
		     Column = integer()
		     Indentation = integer()
		     Text = [string()]

	      Attaches	comments to the syntax tree/trees representing a program. The given Forms should be a single syntax tree of type form_list
	      , or a list of syntax trees representing "program forms". The syntax trees must contain valid position information (for details, see
	      recomment_tree/2 ). The result is a corresponding syntax tree of type form_list in which all comments in the list Comments have been
	      attached at the proper places.

	      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  rep-
	      resenting  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 .

       recomment_tree(Tree::syntaxTree(), Comments::[Comment]) -> {syntaxTree(), [Comment]}

	      Types  Comment = {Line, Column, Indentation, Text}
		     Line = integer()
		     Column = integer()
		     Indentation = integer()
		     Text = [string()]

	      Attaches comments to a syntax tree. The result is a pair {NewTree, Remainder} where NewTree is the given Tree  where  comments  from
	      the  list  Comments  have  been  attached  at  the  proper  places. Remainder is the list of entries in Comments which have not been
	      inserted, because their line numbers are greater than those of any node in the tree. The entries in Comments are inserted in  order;
	      if two comments become attached to the same node, they will appear in the same order in the program text.

	      The  nodes of the syntax tree must contain valid position information. This can be single integers, assumed to represent a line num-
	      ber, 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).

	      For details on the Line , Column and Indentation fields, and the behaviour in case of errors, see recomment_forms/2 .

	      See also: recomment_forms/2 .

AUTHORS

       Richard Carlsson <richardc@it.uu.se >

								syntax_tools 1.6.7					       erl_recomment(3erl)