-/* optimize_in_place (n) may change the contents of the ir_node itself,
- [e.g. by making it a Id-node], but does not change its identity.
- So it is safe to be called on already referenced nodes.
-
- optimize_in_place (n) returns a pointer to a node equivalent to `n'
- which should be used instead of `n'.
-
- optimize (n) may deallocate `n' and everything allocated after `n'! */
-
-tarval *computed_value (ir_node *n);
-
+/** If the expression referenced can be evaluated statically
+ * computed_value returns a tarval representing the result.
+ * Else returns tarval_bad. */
+tarval *computed_value (ir_node *n);
+
+/** Applies all optimizations to n that are expressible as a pattern
+ * in Firm, i.e., they need not a walk of the graph.
+ * Returns a better node for n. Does not free n -- other nodes could
+ * reference n.
+ *
+ * An equivalent optimization is applied in the constructors defined in
+ * ircons.ch. There n is freed if a better node could be found.
+ */