gcc-wwwdocs branch master updated. 00449f252c39605f631af527472db67b1fe53ba2

gcc-wwwdocs branch master updated. 00449f252c39605f631af527472db67b1fe53ba2

[Martin Sebor]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "gcc-wwwdocs".

The branch, master has been updated
       via  00449f252c39605f631af527472db67b1fe53ba2 (commit)
      from  6ae64fd7b9d90950ce53397a298e3b81fffe7a81 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 00449f252c39605f631af527472db67b1fe53ba2
Author: Martin Sebor <msebor@redhat.com>
Date:   Mon Mar 30 20:38:51 2020 -0600

    PR 61339 - mismatch between struct and class [-Wmismatched-tags]
    
    ChangeLog:
    
            * htdocs/codingconventions.html (Struct Definitions): Remove
            old convention.
            (Class Definitions): Same.
            * htdocs/codingrationale.html (Struct Definitions): Document
            convention change.

diff --git a/htdocs/codingconventions.html b/htdocs/codingconventions.html
index 03a77063..f4732ef6 100644
--- a/htdocs/codingconventions.html
+++ b/htdocs/codingconventions.html
@@ -888,9 +888,20 @@ Variables may be simultaneously defined and tested in control expressions.
 <h4 id="Struct_Use">Struct Definitions</h4>
 
 <p>
-Use the <code>struct</code> keyword for
-<a href="https://en.wikipedia.org/wiki/Plain_old_data_structure">
-plain old data (POD)</a> types.
+Some coding conventions, including GCC's own in the past, recommend
+using the <code>struct</code> keyword (also known as the <i>class-key</i>)
+for <a href="https://en.wikipedia.org/wiki/Plain_old_data_structure">
+plain old data (POD)</a> types.  However, since the POD concept has been
+replaced in C++ by a set of much more nuanced distinctions, the current
+guidance (though not a requirement) is to use the <code>struct</code>
+<i>class-key</i> when defining structures that could be used without
+change in C, and use <code>class</code> for all other classes.  It is
+recommended to use the same <i>class-key</i> consistently in all
+declarations and, if necessary, in uses of the class.
+The <code>-Wmismatched-tags</code> warning option helps detect mismatches.
+The <code>-Wredundant-tags</code> GCC option further helps identify places
+where the <i>class-key</i> can safely be omitted.
+
 </p>
 
 <p>
@@ -900,14 +911,13 @@ plain old data (POD)</a> types.
 <h4 id="Class_Use">Class Definitions</h4>
 
 <p>
-Use the <code>class</code> keyword for 
-<a href="https://en.wikipedia.org/wiki/Plain_old_data_structure">
-non-POD</a> types.
+See the guidance in <a href="#Struct_Use">Struct Definitions</a> for
+the suggested choice of a <i>class-key</i>.
 </p>
 
 <p>
-A non-POD type will often (but not always)
-have a declaration of a
+A class defined with the class-key <code>class</code> type will often
+(but not always) ave a declaration of a
 <a href="https://en.wikipedia.org/wiki/Special_member_functions">
 special member function</a>.
 If any one of these is declared,
diff --git a/htdocs/codingrationale.html b/htdocs/codingrationale.html
index a2618b64..0b44f1da 100644
--- a/htdocs/codingrationale.html
+++ b/htdocs/codingrationale.html
@@ -54,15 +54,16 @@ if (info *q = get_any_available_info ()) {
 <h4 id="struct">Struct Definitions</h4>
 
 <p>
-In the C++ standard,
-structs and classes differ only in the default access rules.
-We prefer to use these two keywords to signal more information.
-</p>
-
-<p>
-Note that under this definition,
-structs may have member functions.
-This freedom is useful for transitional code.
+In the C++ standard, structs and classes differ only in the default
+access rules.  In the past, there was a mild preference among some
+GCC developers for using these two keywords to indicate whether or
+not a class met the criteria for a Plain Old Data (POD) type.
+However, this convention was never consistently adhered to or fully
+socialized.  A review of a patch to
+<a href="https://gcc.gnu.org/pipermail/gcc-patches/2019-July/525526.html">
+add support for POD struct convention (PR 61339)</a> revealed that
+the convention lacked broad enough support within the GCC developer
+community.  As a result, the convention was removed.
 </p>
 
 

-----------------------------------------------------------------------

Summary of changes:
 htdocs/codingconventions.html | 26 ++++++++++++++++++--------
 htdocs/codingrationale.html   | 19 ++++++++++---------
 2 files changed, 28 insertions(+), 17 deletions(-)


hooks/post-receive
-- 
gcc-wwwdocs