[PATCH/coding style] clarify pointers and operators

[Martin Sebor <msebor@gmail.com>]

Martin suggested we update the Coding Conventions to describe
the expected style for function declarations with a pointer
return types, and for overloaded operators.  Below is the patch.

As an aside, regarding the space convention in casts: a crude
grep search yields about 10,000 instances of the "(type)x" kinds
of casts in GCC sources and 40,000 of the preferred "(type) x"
style with the space.  That's a consistency of only 80%.  Is
it worth documenting a preference for a convention that's so
inconsistently followed?

Martin

Index: htdocs/codingconventions.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/codingconventions.html,v
retrieving revision 1.85
diff -u -r1.85 codingconventions.html
--- htdocs/codingconventions.html	30 Sep 2018 14:38:46 -0000	1.85
+++ htdocs/codingconventions.html	26 Nov 2018 17:59:21 -0000
@@ -803,12 +803,17 @@
    <td><code>- x</code></td>
  </tr><tr>
    <td class="left">cast</td>
-  <td class="right"><code>(foo) x</code></td>
-  <td><code>(foo)x</code></td>
+  <td class="right"><code>(type) x</code></td>
+  <td><code>(type)x</code></td>
  </tr><tr>
-  <td class="left">pointer dereference</td>
-  <td class="right"><code>*x</code></td>
-  <td><code>* x</code></td>
+  <td class="left">pointer cast</td>
+  <td class="right"><code>(type *) x</code></td>
+  <td><code>(type*)x</code></td>
+</tr>
+</tr><tr>
+  <td class="left">pointer return type</td>
+  <td class="right"><code>type *f (void)</code></td>
+  <td><code>type* f (void)</code></td>
  </tr>
  </table>

@@ -992,6 +997,21 @@
  <a href="codingrationale.html#overoper">Rationale and Discussion</a>
  </p>

+<p>
+Note: in declarations of operator functions or in invocations of
+such functions that involve the keyword <code>operator</code>
+the full name of the operator should be considered as including
+the keyword with no spaces in between the keyowrd and the operator
+token.  Thus, the expected format of a declaration of an operator
+is<pre>
+    T &amp;operator== (const T &amp; const T &amp);
+</pre>
+and not for example<pre>
+    T &amp;operator == (const T &amp; const T &amp);
+</pre>
+(with the space between <code>operator</code> and <code>==</code>).
+</p>
+

  <h4 id="Default">Default Arguments</h4>