Document which check flags are completely set by semantic analysis,
including in ASIS mode and GNATprove mode, and which check flags are
only partially set. Analysis tools based on a tree obtained by
semantic analysis only should thus rely only on the first category of
flags to be set in the tree.
Tested on x86_64-pc-linux-gnu, committed on trunk
2014-01-24 Yannick Moy <m...@adacore.com>
* sinfo.ads: Add documentation of check flag fields.
Index: sinfo.ads
===================================================================
--- sinfo.ads (revision 207026)
+++ sinfo.ads (working copy)
@@ -516,12 +516,12 @@
-- expansion is performed and the analysis must generate a tree in a
-- form that meets additional requirements.
- -- This light expansion does two transformations of the tree, that cannot
- -- be postponed after the frontend semantic analysis:
+ -- This light expansion does two transformations of the tree that cannot
+ -- be postponed after semantic analysis:
-- 1. Replace object renamings by renamed object. This requires the
- -- introdtion of temporaries at the point of the renaming, which must
- -- be properly analyzed.
+ -- introduction of temporaries at the point of the renaming, which
+ -- must be properly analyzed.
-- 2. Fully qualify entity names. This is needed to generate suitable
-- local effects and call-graphs in ALI files, with the completely
@@ -549,6 +549,39 @@
-- not make sense from a user point-of-view, and that cross-references that
-- do not lead to data dependences for subprograms can be safely ignored.
+ -----------------------
+ -- Check Flag Fields --
+ -----------------------
+
+ -- The following flag fields appear in expression nodes:
+
+ -- Do_Division_Check
+ -- Do_Overflow_Check
+ -- Do_Range_Check
+
+ -- These three flags are always set by the front end during semantic
+ -- analysis, on expression nodes that may trigger the corresponding
+ -- check. The front end then inserts or not the check during expansion.
+ -- In particular, these flags should also be correctly set in ASIS mode
+ -- and GNATprove mode.
+
+ -- Note that this accounts for all nodes that trigger the corresponding
+ -- checks, except for range checks on subtype_indications, which may be
+ -- required to check that a range_constraint is compatible with the given
+ -- subtype (RM 3.2.2(11)).
+
+ -- The following flag fields appear in various nodes:
+
+ -- Do_Accessibility_Check
+ -- Do_Discriminant_Check
+ -- Do_Length_Check
+ -- Do_Storage_Check
+ -- Do_Tag_Check
+
+ -- These flags are used in some specific cases by the front end, either
+ -- during semantic analysis or during expansion, and cannot be expected
+ -- to be set on all nodes that trigger the corresponding check.
+
------------------------
-- Common Flag Fields --
------------------------
@@ -7325,7 +7358,7 @@
-- N_Expression_With_Actions has type Standard_Void_Type. However some
-- backends do not support such expression-with-actions occurring
-- outside of a proper (non-void) expression, so this should just be
- -- used as an intermediate representation within the front-end. Also
+ -- used as an intermediate representation within the front end. Also
-- note that this is really an irregularity (expressions and statements
-- are not interchangeable, and in particular an N_Null_Statement is
-- not a proper expression), and in the long term all cases of this
@@ -7746,7 +7779,7 @@
-- e.g. involving unconstrained array types.
-- For the case of the standard gigi backend, this means that all
- -- checks are done in the front-end.
+ -- checks are done in the front end.
-- However, in the case of specialized back-ends, notably the JVM
-- backend for JGNAT, additional requirements and restrictions apply
