[gcc/devel/omp/gcc-16] OpenMP: Improve interface comment for the omp_deep_mapping lang hooks

https://gcc.gnu.org/g:e3d7a5c069ef7362ba3088e17b2e511be42643f3

commit e3d7a5c069ef7362ba3088e17b2e511be42643f3
Author: Tobias Burnus <[email protected]>
Date:   Thu May 14 11:41:22 2026 +0200

    OpenMP: Improve interface comment for the omp_deep_mapping lang hooks
    
    gcc/fortran/ChangeLog:
    
            * trans-openmp.cc (gfc_omp_deep_mapping_p, gfc_omp_deep_mapping_cnt,
            gfc_omp_deep_mapping): Improve interface comment.
    
    gcc/ChangeLog:
    
            * langhooks.cc (lhd_omp_deep_mapping_p, lhd_omp_deep_mapping_cnt,
            lhd_omp_deep_mapping): Improve interface comment.
            * langhooks.h (lhd_omp_deep_mapping_p, lhd_omp_deep_mapping_cnt,
            lhd_omp_deep_mapping): Likewise
    
    (cherry picked from commit 844294c96a9fe8415277d46c54b576d1d80fe449)

Diff:
---
 gcc/fortran/trans-openmp.cc | 28 +++++++++++++++++++++++-----
 gcc/langhooks.cc            |  9 ++++++---
 gcc/langhooks.h             | 19 ++++++++++++++-----
 3 files changed, 43 insertions(+), 13 deletions(-)

diff --git a/gcc/fortran/trans-openmp.cc b/gcc/fortran/trans-openmp.cc
index b9c09d114b73..680e43c1cc02 100644
--- a/gcc/fortran/trans-openmp.cc
+++ b/gcc/fortran/trans-openmp.cc
@@ -2475,8 +2475,11 @@ gfc_omp_deep_mapping_int_p (const gimple *ctx, tree clause)
   return decl;
 }
 
-/* Return true if there is deep mapping, even if the number of mapping is known
-   at compile time. */
+/* Return true if there is any deep mapping required, even if the number of
+   mappings is known at compile time.  Deep mapping is required if the passed
+   CLAUSE is a map clause and its OMP_CLAUSE_DECL refers to a derived-type with
+   allocatable components. CTX is the statement that contains the CLAUSE.  */
+
 bool
 gfc_omp_deep_mapping_p (const gimple *ctx, tree clause)
 {
@@ -2622,8 +2625,14 @@ gfc_omp_deep_mapping_do (bool is_cnt, const gimple *ctx, tree clause,
   return num;
 }
 
-/* Return tree with a variable which contains the count of deep-mappyings
-   (value depends, e.g., on allocation status)  */
+/* Returns NULL_TREE if known that no deep mapping is required for the passed
+   'map' CLAUSE, otherwise returns a size_type expression with the number of
+   required data-mapping operations, which may be zero.  Deep mapping is
+   required for allocatable components of derived types; the number of mapping
+   operations depends on the allocation status, array sizes and the dynamic
+   type.  CTX is the gimple statement that contains the map CLAUSE; the
+   gimple code used for counting is added to SEQ.  */
+
 tree
 gfc_omp_deep_mapping_cnt (const gimple *ctx, tree clause, gimple_seq *seq)
 {
@@ -2631,7 +2640,16 @@ gfc_omp_deep_mapping_cnt (const gimple *ctx, tree clause, gimple_seq *seq)
 				  NULL_TREE, NULL_TREE, NULL_TREE, seq);
 }
 
-/* Does the actual deep mapping. */
+/* Handle the deep mapping for the passed map CLAUSE that is part of
+   the gimple statement CTX by walking all allocated allocatable components
+   and its allocatable components to add additional data-mapping operations.
+   TKIND is the map-type/kind to be used. The generated code is added to
+   SEQ – and the actual struct-field address used for mapping, the map size,
+   and kind value to the arrays DATA, SIZES, and KINDS, respectively.
+   OFFSET_DATA and OFFSET are size-type variables; the map operatations are
+   added at array index OFFSET_DATA for DATA and at array index OFFSET for
+   SIZES/KINDS, incrementing the offsets after each assignment.  */
+
 void
 gfc_omp_deep_mapping (const gimple *ctx, tree clause,
 		      unsigned HOST_WIDE_INT tkind, tree data,
diff --git a/gcc/langhooks.cc b/gcc/langhooks.cc
index e2c7735596e0..d55e2ca78560 100644
--- a/gcc/langhooks.cc
+++ b/gcc/langhooks.cc
@@ -646,7 +646,8 @@ lhd_omp_array_size (tree, gimple_seq *)
   return NULL_TREE;
 }
 
-/* Returns true when additional mappings for a decl are needed.  */
+/* Return false, implying that no additional data-mapping operations
+   are required for the tree containing a map clause.  */
 
 bool
 lhd_omp_deep_mapping_p (const gimple *, tree)
@@ -654,7 +655,8 @@ lhd_omp_deep_mapping_p (const gimple *, tree)
   return false;
 }
 
-/* Returns number of additional mappings for a decl.  */
+/* Return NULL_TREE, implying that no additional data-mapping operations
+   are required for the tree containing a map clause.  */
 
 tree
 lhd_omp_deep_mapping_cnt (const gimple *, tree, gimple_seq *)
@@ -662,7 +664,8 @@ lhd_omp_deep_mapping_cnt (const gimple *, tree, gimple_seq *)
   return NULL_TREE;
 }
 
-/* Do the additional mappings.  */
+/* Do nothing as no additional data-mapping operations
+   are required for the second argument that contains a map clause.  */
 
 void
 lhd_omp_deep_mapping (const gimple *, tree, unsigned HOST_WIDE_INT, tree, tree,
diff --git a/gcc/langhooks.h b/gcc/langhooks.h
index 6eb5c1602f83..cfcb38092d58 100644
--- a/gcc/langhooks.h
+++ b/gcc/langhooks.h
@@ -313,16 +313,25 @@ struct lang_hooks_for_decls
   /* Do language specific checking on an implicitly determined clause.  */
   void (*omp_finish_clause) (tree clause, gimple_seq *pre_p, bool);
 
-  /* Additional language-specific mappings for a decl; returns true
-     if those may occur.  */
+  /* Return true if for the passed OpenMP 'map' CLAUSE, additional data-mapping
+     is required; CTX_STMT is the gimple statement containing the clause.
+     Otherwise, false is returned.  */
   bool (*omp_deep_mapping_p) (const gimple *ctx_stmt, tree clause);
 
-  /* Additional language-specific mappings for a decl; returns the
-     number of additional mappings needed.  */
+  /* Return the number of additional data-mappings required for the passed
+     'map' CLAUSE; CTX_STMT is the gimple statement containing the clause.
+     It is NULL_TREE if known that no such mapping are required and otherwise
+     of type size_type_node and usually non-constant.  */
   tree (*omp_deep_mapping_cnt) (const gimple *ctx_stmt, tree clause,
 				gimple_seq *seq);
 
-  /* Do the actual additional language-specific mappings for a decl. */
+  /* If no additional data-mapping is required for the passed 'map' CLAUSE that
+     is part of the CTX_SMT gimple statement, the function has no effect.
+     Otherwise, DATA refers to a void-pointer array containing the address values
+     of the mapping while SIZE and KINDS are arrays for the to-be mapped size and
+     the map kind; OFFSET_DATA and OFFSET are size_type_node variable that refer
+     to the array index of DATA and SIZE/KIND, respectively and are incremented
+     whenever an element is added. New gimple code is added to SEQ.  */
   void (*omp_deep_mapping) (const gimple *stmt, tree clause,
 			    unsigned HOST_WIDE_INT tkind,
 			    tree data, tree sizes, tree kinds,