tree-flow-inline.h: Document all functions.

2004-06-15  Daniel Berlin  <dberlin@dberlin.org>

	* tree-flow-inline.h: Document all functions.

From-SVN: r83197

2 files changed, 92 insertions, 3 deletions

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index a9cfaae..200cdd4 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,5 +1,9 @@
 2004-06-15  Daniel Berlin  <dberlin@dberlin.org>
 
+	* tree-flow-inline.h: Document all functions.
+	
+2004-06-15  Daniel Berlin  <dberlin@dberlin.org>
+
 	* tree-flow-inline.h (stmt_ann): Remove use of is_essa_node.
 	* tree-dfa.c (create_stmt_ann): Ditto.
 	* tree-pretty-print.c (dump_generic_node): Remove E* node handling.
diff --git a/gcc/tree-flow-inline.h b/gcc/tree-flow-inline.h
index 5ecaa1d..17eb6db 100644
--- a/gcc/tree-flow-inline.h
+++ b/gcc/tree-flow-inline.h
@@ -25,6 +25,8 @@ Boston, MA 02111-1307, USA.  */
 /* Inline functions for manipulating various data structures defined in
    tree-flow.h.  See tree-flow.h for documentation.  */
 
+/* Return the variable annotation for T, which must be a _DECL node.
+   Return NULL if the variable annotation doesn't already exist.  */
 static inline var_ann_t
 var_ann (tree t)
 {
@@ -39,6 +41,8 @@ var_ann (tree t)
   return (var_ann_t) t->common.ann;
 }
 
+/* Return the variable annotation for T, which must be a _DECL node.
+   Create the variable annotation if it doesn't exist.  */
 static inline var_ann_t
 get_var_ann (tree var)
 {
@@ -47,6 +51,8 @@ get_var_ann (tree var)
 }
 
 
+/* Return the constant annotation for T, which must be a _CST node.
+   Return NULL if the constant annotation doesn't already exist.  */
 static inline cst_ann_t
 cst_ann (tree t)
 {
@@ -60,6 +66,8 @@ cst_ann (tree t)
   return (cst_ann_t) t->common.ann;
 }
 
+/* Return the constant annotation for T, which must be a _CST node.
+   Create the constant annotation if it doesn't exist.  */
 static inline cst_ann_t
 get_cst_ann (tree var)
 {
@@ -67,6 +75,9 @@ get_cst_ann (tree var)
   return (ann) ? ann : create_cst_ann (var);
 }
 
+/* Return the expression annotation for T, which must be an expression
+   node.  Return NULL if the expression annotation doesn't already
+   exist.  */
 static inline expr_ann_t
 expr_ann (tree t)
 {
@@ -80,13 +91,17 @@ expr_ann (tree t)
   return (expr_ann_t) t->common.ann;
 }
 
+/* Return the expression annotation for T, which must be an expression
+   node.  Create the expression annotation if it doesn't exist.  */
 static inline expr_ann_t
-get_expr_ann (tree var)
+get_expr_ann (tree t)
 {
-  expr_ann_t ann = expr_ann (var);
-  return (ann) ? ann : create_expr_ann (var);
+  expr_ann_t ann = expr_ann (t);
+  return (ann) ? ann : create_expr_ann (t);
 }
 
+/* Return the statement annotation for T, which must be a statement
+   node.  Return NULL if the statement annotation doesn't exist.  */
 static inline stmt_ann_t
 stmt_ann (tree t)
 {
@@ -98,6 +113,8 @@ stmt_ann (tree t)
   return (stmt_ann_t) t->common.ann;
 }
 
+/* Return the statement annotation for T, which must be a statement
+   node.  Create the statement annotation if it doesn't exist.  */
 static inline stmt_ann_t
 get_stmt_ann (tree stmt)
 {
@@ -106,12 +123,14 @@ get_stmt_ann (tree stmt)
 }
 
 
+/* Return the annotation type for annotation ANN.  */
 static inline enum tree_ann_type
 ann_type (tree_ann ann)
 {
   return ann->common.type;
 }
 
+/* Return the basic block for statement T.  */
 static inline basic_block
 bb_for_stmt (tree t)
 {
@@ -119,6 +138,8 @@ bb_for_stmt (tree t)
   return ann ? ann->bb : NULL;
 }
 
+/* Return the may_aliases varray for variable VAR, or NULL if it has
+   no may aliases.  */
 static inline varray_type
 may_aliases (tree var)
 {
@@ -126,6 +147,7 @@ may_aliases (tree var)
   return ann ? ann->may_aliases : NULL;
 }
 
+/* Return true if VAR has a hidden use, false if it does not.  */
 static inline bool
 has_hidden_use (tree var)
 {
@@ -133,6 +155,7 @@ has_hidden_use (tree var)
   return ann ? ann->has_hidden_use : false;
 }
 
+/* Set the hidden use flag on VAR.  */ 
 static inline void
 set_has_hidden_use (tree var)
 {
@@ -142,6 +165,8 @@ set_has_hidden_use (tree var)
   ann->has_hidden_use = 1;
 }
 
+/* Return the line number for EXPR, or return -1 if we have no line
+   number information for it.  */
 static inline int
 get_lineno (tree expr)
 {
@@ -157,6 +182,8 @@ get_lineno (tree expr)
   return EXPR_LINENO (expr);
 }
 
+/* Return the file name for EXPR, or return "???" if we have no
+   filename information.  */
 static inline const char *
 get_filename (tree expr)
 {
@@ -172,6 +199,7 @@ get_filename (tree expr)
     return "???";
 }
 
+/* Mark statement T as modified.  */
 static inline void
 modify_stmt (tree t)
 {
@@ -181,6 +209,7 @@ modify_stmt (tree t)
   ann->modified = 1;
 }
 
+/* Mark statement T as unmodified.  */
 static inline void
 unmodify_stmt (tree t)
 {
@@ -190,6 +219,7 @@ unmodify_stmt (tree t)
   ann->modified = 0;
 }
 
+/* Return true if T is marked as modified, false otherwise.  */
 static inline bool
 stmt_modified_p (tree t)
 {
@@ -201,36 +231,48 @@ stmt_modified_p (tree t)
   return ann ? ann->modified : true;
 }
 
+/* Return the definitions present in ANN, a statement annotation.
+   Return NULL if this annotation contains no definitions.  */
 static inline def_optype
 get_def_ops (stmt_ann_t ann)
 {
   return ann ? ann->def_ops : NULL;
 }
 
+/* Return the uses present in ANN, a statement annotation.
+   Return NULL if this annotation contains no uses.  */
 static inline use_optype
 get_use_ops (stmt_ann_t ann)
 {
   return ann ? ann->use_ops : NULL;
 }
 
+/* Return the virtual may-defs present in ANN, a statement
+   annotation.
+   Return NULL if this annotation contains no virtual may-defs.  */
 static inline v_may_def_optype
 get_v_may_def_ops (stmt_ann_t ann)
 {
   return ann ? ann->v_may_def_ops : NULL;
 }
 
+/* Return the virtual uses present in ANN, a statement annotation.
+   Return NULL if this annotation contains no virtual uses.  */
 static inline vuse_optype
 get_vuse_ops (stmt_ann_t ann)
 {
   return ann ? ann->vuse_ops : NULL;
 }
 
+/* Return the virtual must-defs present in ANN, a statement
+   annotation.  Return NULL if this annotation contains no must-defs.*/
 static inline v_must_def_optype
 get_v_must_def_ops (stmt_ann_t ann)
 {
   return ann ? ann->v_must_def_ops : NULL;
 }
 
+/* Return a pointer to the tree that is at INDEX in the USES array.  */
 static inline tree *
 get_use_op_ptr (use_optype uses, unsigned int index)
 {
@@ -241,6 +283,7 @@ get_use_op_ptr (use_optype uses, unsigned int index)
   return uses->uses[index];
 }
 
+/* Return a pointer to the tree that is at INDEX in the DEFS array.  */
 static inline tree *
 get_def_op_ptr (def_optype defs, unsigned int index)
 {
@@ -251,6 +294,9 @@ get_def_op_ptr (def_optype defs, unsigned int index)
   return defs->defs[index];
 }
 
+
+/* Return a pointer to the tree that is the V_MAY_DEF_RESULT for the V_MAY_DEF
+   at INDEX in the V_MAY_DEFS array.  */
 static inline tree *
 get_v_may_def_result_ptr(v_may_def_optype v_may_defs, unsigned int index)
 {
@@ -261,6 +307,8 @@ get_v_may_def_result_ptr(v_may_def_optype v_may_defs, unsigned int index)
   return &(v_may_defs->v_may_defs[index * 2]);
 }
 
+/* Return a pointer to the tree that is the V_MAY_DEF_OP for the V_MAY_DEF at
+   INDEX in the V_MAY_DEFS array.  */
 static inline tree *
 get_v_may_def_op_ptr(v_may_def_optype v_may_defs, unsigned int index)
 {
@@ -271,6 +319,7 @@ get_v_may_def_op_ptr(v_may_def_optype v_may_defs, unsigned int index)
   return &(v_may_defs->v_may_defs[index * 2 + 1]);
 }
 
+/* Return a pointer to the tree that is at INDEX in the VUSES array.  */
 static inline tree *
 get_vuse_op_ptr(vuse_optype vuses, unsigned int index)
 {
@@ -281,6 +330,8 @@ get_vuse_op_ptr(vuse_optype vuses, unsigned int index)
   return &(vuses->vuses[index]);
 }
 
+/* Return a pointer to the tree that is the V_MUST_DEF_OP for the
+   V_MUST_DEF at INDEX in the V_MUST_DEFS array.  */
 static inline tree *
 get_v_must_def_op_ptr (v_must_def_optype v_must_defs, unsigned int index)
 {
@@ -291,6 +342,7 @@ get_v_must_def_op_ptr (v_must_def_optype v_must_defs, unsigned int index)
   return &(v_must_defs->v_must_defs[index]);
 }
 
+/* Mark the beginning of changes to the SSA operands for STMT.  */
 static inline void
 start_ssa_stmt_operands (tree stmt ATTRIBUTE_UNUSED)
 {
@@ -299,6 +351,8 @@ start_ssa_stmt_operands (tree stmt ATTRIBUTE_UNUSED)
 #endif
 }
 
+/* Return the bitmap of addresses taken by STMT, or NULL if it takes
+   no addresses.  */
 static inline bitmap
 addresses_taken (tree stmt)
 {
@@ -306,6 +360,8 @@ addresses_taken (tree stmt)
   return ann ? ann->addresses_taken : NULL;
 }
 
+/* Return the immediate uses of STMT, or NULL if this information is
+   not computed.  */
 static dataflow_t
 get_immediate_uses (tree stmt)
 {
@@ -313,6 +369,8 @@ get_immediate_uses (tree stmt)
   return ann ? ann->df : NULL;
 }
 
+/* Return the number of immediate uses present in the dataflow
+   information at DF.  */
 static inline int
 num_immediate_uses (dataflow_t df)
 {
@@ -328,6 +386,7 @@ num_immediate_uses (dataflow_t df)
   return VARRAY_ACTIVE_SIZE (imm) + 2;
 }
 
+/* Return the tree that is at NUM in the immediate use DF array.  */
 static inline tree
 immediate_use (dataflow_t df, int num)
 {
@@ -343,12 +402,15 @@ immediate_use (dataflow_t df, int num)
   return VARRAY_TREE (df->immediate_uses, num - 2);
 }
 
+/* Return the basic_block annotation for BB.  */
 static inline bb_ann_t
 bb_ann (basic_block bb)
 {
   return (bb_ann_t)bb->tree_annotations;
 }
 
+/* Return the PHI nodes for basic block BB, or NULL if there are no
+   PHI nodes.  */
 static inline tree
 phi_nodes (basic_block bb)
 {
@@ -402,6 +464,7 @@ phi_element_for_edge (tree phi, edge e)
 
 /*  -----------------------------------------------------------------------  */
 
+/* Return true if T is an executable statement.  */
 static inline bool
 is_exec_stmt (tree t)
 {
@@ -427,6 +490,7 @@ is_label_stmt (tree t)
   return false;
 }
 
+/* Return true if we may propagate ORIG into DEST, false otherwise.  */
 static inline bool
 may_propagate_copy (tree dest, tree orig)
 {
@@ -507,6 +571,7 @@ may_propagate_copy (tree dest, tree orig)
 	  && !DECL_HARD_REGISTER (SSA_NAME_VAR (dest)));
 }
 
+/* Set the default definition for VAR to DEF.  */
 static inline void
 set_default_def (tree var, tree def)
 {
@@ -516,6 +581,8 @@ set_default_def (tree var, tree def)
   ann->default_def = def;
 }
 
+/* Return the default definition for variable VAR, or NULL if none
+   exists.  */
 static inline tree
 default_def (tree var)
 {
@@ -541,6 +608,8 @@ phi_ssa_name_p (tree t)
 
 /*  -----------------------------------------------------------------------  */
 
+/* Return a block_stmt_iterator that points to beginning of basic
+   block BB.  */
 static inline block_stmt_iterator
 bsi_start (basic_block bb)
 {
@@ -560,6 +629,8 @@ bsi_start (basic_block bb)
   return bsi;
 }
 
+/* Return a block statement iterator that points to the end of basic
+   block BB.  */
 static inline block_stmt_iterator
 bsi_last (basic_block bb)
 {
@@ -579,36 +650,47 @@ bsi_last (basic_block bb)
   return bsi;
 }
 
+/* Return true if block statement iterator I has reached the end of
+   the basic block.  */
 static inline bool
 bsi_end_p (block_stmt_iterator i)
 {
   return tsi_end_p (i.tsi);
 }
 
+/* Modify block statement iterator I so that it is at the next
+   statement in the basic block.  */
 static inline void
 bsi_next (block_stmt_iterator *i)
 {
   tsi_next (&i->tsi);
 }
 
+/* Modify block statement iterator I so that it is at the previous
+   statement in the basic block.  */
 static inline void
 bsi_prev (block_stmt_iterator *i)
 {
   tsi_prev (&i->tsi);
 }
 
+/* Return the statement that block statement iterator I is currently
+   at.  */
 static inline tree
 bsi_stmt (block_stmt_iterator i)
 {
   return tsi_stmt (i.tsi);
 }
 
+/* Return a pointer to the statement that block statement iterator I
+   is currently at.  */
 static inline tree *
 bsi_stmt_ptr (block_stmt_iterator i)
 {
   return tsi_stmt_ptr (i.tsi);
 }
 
+/* Return true if VAR may be aliased.  */
 static inline bool
 may_be_aliased (tree var)
 {
@@ -616,6 +698,7 @@ may_be_aliased (tree var)
           || decl_function_context (var) != current_function_decl);
 }
 
+/* Return true if VAR is a clobbered by function calls.  */
 static inline bool
 is_call_clobbered (tree var)
 {
@@ -623,6 +706,7 @@ is_call_clobbered (tree var)
 	 || bitmap_bit_p (call_clobbered_vars, var_ann (var)->uid);
 }
 
+/* Mark variable VAR as being clobbered by function calls.  */
 static inline void
 mark_call_clobbered (tree var)
 {
@@ -632,6 +716,7 @@ mark_call_clobbered (tree var)
   bitmap_set_bit (call_clobbered_vars, ann->uid);
 }
 
+/* Mark variable VAR as being non-addressable.  */
 static inline void
 mark_non_addressable (tree var)
 {