-extern bool interprocedural_view;
-bool get_interprocedural_view(void);
-void set_interprocedural_view(bool state);
-
-/** Create a new ir graph to built ir for a procedure.
- *
- * ent is the entity representing this procedure, i.e., the type of the
- * entity must be of a method type. The constructor automatically sets the
- * field irg of the entity as well as current_ir_graph to the new ir graph.
- * n_loc is the number of local variables in this procedure including
- * the procedure parameters.
- * The constructor adds the new irgraph to the list in ir_prog.
- * The state of the ir graph is: phase_building, op_pin_state_pinned, outs_none. */
+int get_interprocedural_view(void);
+void set_interprocedural_view(int state);
+
+/**
+ * Create a new ir graph to build ir for a procedure.
+ *
+ * @param ent A pointer to an entity representing the procedure,
+ * i.e., the type of the entity must be of a method type.
+ *
+ * @param n_loc The number of local variables in this procedure including
+ * the procedure parameters.
+ *
+ * This constructor generates the basic infrastructure needed to
+ * represent a procedure in FIRM.
+ *
+ * It allocates an ir_graph and sets the field irg of the entity ent
+ * as well as current_ir_graph to point to this graph.
+ * Further it allocates the following nodes needed for every
+ * procedure:
+ *
+ * - The start block containing a start node and Proj nodes for it's
+ * five results (X, M, P, P, T).
+ * - The end block containing an end node. This block is not matured
+ * after executing new_ir_graph as predecessors need to be added to it.
+ * (Maturing a block means fixing it's number of predecessors.)
+ * - The current block, which is empty and also not matured.
+ *
+ * Further it enters the global store into the datastructure of the start
+ * block that contanis all valid values in this block (set_store()). This
+ * datastructure is used to build the Phi nodes and removed after
+ * completion of the graph. There is no path from end to start in the
+ * graph after calling ir_graph.
+ *
+ * The op_pin_state of the graph is set to "op_pin_state_pinned"
+ * if no global cse was performed on the graph.
+ * It is set to "op_pin_state_floats" if global cse was performed
+ * (and during construction: did actually change something).
+ * Code placement is necessary.
+ *
+ * @see new_pseudo_ir_graph()
+ */