[gcc r13-4191] ada: Improve documentation for -gnatw.h warnings

[Marc Poulhi?s <dkm@gcc.gnu.org>]

https://gcc.gnu.org/g:84e80d556415c4c82081647e70e899506a7db9ba

commit r13-4191-g84e80d556415c4c82081647e70e899506a7db9ba
Author: Steve Baird <baird@adacore.com>
Date:   Wed Nov 9 15:53:49 2022 -0800

    ada: Improve documentation for -gnatw.h warnings
    
    The -gnatw.h option enables warnings about "gaps" in record layout
    specifications. In the case of a "partial" layout specification, where the
    locations of some components are left unspecified, the resulting warnings
    may be incomplete or incorrect. Document this implementation limitation.
    
    gcc/ada/
    
            * doc/gnat_ugn/building_executable_programs_with_gnat.rst: Improve
            the description of how the -gnatw.h switch interacts with
            "partial" record layout specifications (i.e., specifications where
            the locations of some components are left unspecified).
            * gnat_ugn.texi: Regenerate.

Diff:
---
 .../doc/gnat_ugn/building_executable_programs_with_gnat.rst   |  9 +++++++--
 gcc/ada/gnat_ugn.texi                                         | 11 ++++++++---
 2 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst b/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst
index 87fb1087e42..fe0b567c2b9 100644
--- a/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst
+++ b/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst
@@ -3221,8 +3221,13 @@ of the pragma in the :title:`GNAT_Reference_manual`).
 
   This switch activates warnings on component clauses in record
   representation clauses that leave holes (gaps) in the record layout.
-  If this warning option is active, then record representation clauses
-  should specify a contiguous layout, adding unused fill fields if needed.
+  If a record representation clause does not specify a location for
+  every component of the record type, then the warnings generated (or not
+  generated) are unspecified. For example, there may be gaps for which
+  either no warning is generated or a warning is generated that
+  incorrectly describes the location of the gap. This undesirable situation
+  can sometimes be avoided by adding (and specifying the location for) unused
+  fill fields.
 
 
 .. index:: -gnatw.H  (gcc)
diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi
index 2f43b4f71c8..12eb494d40d 100644
--- a/gcc/ada/gnat_ugn.texi
+++ b/gcc/ada/gnat_ugn.texi
@@ -19,7 +19,7 @@
 
 @copying
 @quotation
-GNAT User's Guide for Native Platforms , Nov 14, 2022
+GNAT User's Guide for Native Platforms , Nov 18, 2022
 
 AdaCore
 
@@ -11305,8 +11305,13 @@ This switch suppresses warnings on hiding declarations.
 
 This switch activates warnings on component clauses in record
 representation clauses that leave holes (gaps) in the record layout.
-If this warning option is active, then record representation clauses
-should specify a contiguous layout, adding unused fill fields if needed.
+If a record representation clause does not specify a location for
+every component of the record type, then the warnings generated (or not
+generated) are unspecified. For example, there may be gaps for which
+either no warning is generated or a warning is generated that
+incorrectly describes the location of the gap. This undesirable situation
+can sometimes be avoided by adding (and specifying the location for) unused
+fill fields.
 @end table
 
 @geindex -gnatw.H (gcc)