* tree.def (PLACEHOLDER_EXPR): Update comments.

From-SVN: r30241

1 files changed, 39 insertions, 30 deletions

diff --git a/gcc/tree.def b/gcc/tree.def
index af50d7b..9ccc3c5 100644
--- a/gcc/tree.def
+++ b/gcc/tree.def
@@ -490,39 +490,48 @@ DEFTREECODE (WITH_CLEANUP_EXPR, "with_cleanup_expr", 'e', 3)
 DEFTREECODE (CLEANUP_POINT_EXPR, "cleanup_point_expr", 'e', 1)
 
 /* The following two codes are used in languages that have types where
-   the position and/or sizes of fields vary from object to object of the
-   same type, i.e., where some other field in the object contains a value
-   that is used in the computation of another field's offset or size.
-
-   For example, a record type with a discriminant in Ada is such a type.
-   This mechanism is also used to create "fat pointers" for unconstrained
-   array types in Ada; the fat pointer is a structure one of whose fields is
-   a pointer to the actual array type and the other field is a pointer to a
-   template, which is a structure containing the bounds of the array.  The
-   bounds in the type pointed to by the first field in the fat pointer refer
-   to the values in the template.
-
-   These "self-references" are doing using a PLACEHOLDER_EXPR.  This is a
-   node that will later be replaced with the object being referenced.  Its type
-   is that of the object and selects which object to use from a chain of
-   references (see below).
-
-   When we wish to evaluate a size or offset, we check it is contains a
-   placeholder.  If it does, we construct a WITH_RECORD_EXPR that contains
-   both the expression we wish to evaluate and an expression within which the
-   object may be found.  The latter expression is the object itself in
-   the simple case of an Ada record with discriminant, but it can be the
-   array in the case of an unconstrained array.
-
-   In the latter case, we need the fat pointer, because the bounds of the
-   array can only be accessed from it.  However, we rely here on the fact that
-   the expression for the array contains the dereference of the fat pointer
-   that obtained the array pointer.
+   some field in an object of the type contains a value that is used in
+   the computation of another field's offset or size and/or the size of
+   the type.  The positions and/or sizes of fields can vary from object
+   to object of the same type.
+
+   Record types with discriminants in Ada or schema types in Pascal are
+   examples of such types.  This mechanism is also used to create "fat
+   pointers" for unconstrained array types in Ada; the fat pointer is a
+   structure one of whose fields is a pointer to the actual array type
+   and the other field is a pointer to a template, which is a structure
+   containing the bounds of the array.  The bounds in the type pointed
+   to by the first field in the fat pointer refer to the values in the
+   template.
+
+   When you wish to construct such a type you need "self-references"
+   that allow you to reference the object having this type from the
+   TYPE node, i.e. without having a variable instantiating this type.
+
+   Such a "self-references" is done using a PLACEHOLDER_EXPR.  This is
+   a node that will later be replaced with the object being referenced.
+   Its type is that of the object and selects which object to use from
+   a chain of references (see below).  No other slots are used in the
+   PLACEHOLDER_EXPR.
+
+   For example, if your type FOO is a RECORD_TYPE with a field BAR,
+   and you need the value of <variable>.BAR to calculate TYPE_SIZE
+   (FOO), just substitute <variable> above with a PLACEHOLDER_EXPR
+   what contains both the expression we wish to
+   evaluate and an expression within which the object may be found.
+   The latter expression is the object itself in the simple case of an
+   Ada record with discriminant, but it can be the array in the case of
+   an unconstrained array.
+
+   In the latter case, we need the fat pointer, because the bounds of
+   the array can only be accessed from it.  However, we rely here on the
+   fact that the expression for the array contains the dereference of
+   the fat pointer that obtained the array pointer.
 
    Accordingly, when looking for the object to substitute in place of
    a PLACEHOLDER_EXPR, we look down the first operand of the expression
-   passed as the second operand to WITH_RECORD_EXPR until we find something
-   of the desired type or reach a constant.  */
+   passed as the second operand to WITH_RECORD_EXPR until we find
+   something of the desired type or reach a constant.  */
 
 /* Denotes a record to later be supplied with a WITH_RECORD_EXPR when
    evaluating this expression.  The type of this expression is used to