Add a few more details in the source-code-formatting documentation.

This isn't exhaustive but it covers some of the more common layout
mistakes I've seen in submitted patches.

doc/src/sgml/sources.sgml

-<!-- $PostgreSQL: pgsql/doc/src/sgml/sources.sgml,v 2.30 2008/03/24 18:08:47 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/sources.sgml,v 2.31 2008/09/07 02:01:04 tgl Exp $ -->
 
  <chapter id="source">
   <title>PostgreSQL Coding Conventions</title>
@@ -8,16 +8,48 @@
 
    <para>
     Source code formatting uses 4 column tab spacing, with
-    tabs preserved (i.e. tabs are not expanded to spaces).
+    tabs preserved (i.e., tabs are not expanded to spaces).
     Each logical indentation level is one additional tab stop.
-    Layout rules (brace positioning, etc) follow BSD conventions.
+   </para>
+
+   <para>
+    Layout rules (brace positioning, etc) follow BSD conventions.  In
+    particular, curly braces for the controlled blocks of <literal>if</>,
+    <literal>while</>, <literal>switch</>, etc go on their own lines.
+   </para>
+
+   <para>
+    Do not use C++ style comments (<literal>//</> comments).  Strict ANSI C
+    compilers do not accept them.  For the same reason, do not use C++
+    extensions such as declaring new variables mid-block.
+   </para>
+
+   <para>
+    The preferred style for multi-line comment blocks is
+<programlisting>
+/*
+ * comment text begins here
+ * and continues here
+ */
+</programlisting>
+    Note that comment blocks that begin in column 1 will be preserved as-is
+    by <application>pgindent</>, but it will re-flow indented comment blocks
+    as though they were plain text.  If you want to preserve the line breaks
+    in an indented block, add dashes like this:
+<programlisting>
+    /*----------
+     * comment text begins here
+     * and continues here
+     *----------
+     */
+</programlisting>
    </para>
 
    <para>
     While submitted patches do not absolutely have to follow these formatting
     rules, it's a good idea to do so.  Your code will get run through
-    <application>pgindent</>, so there's no point in making it look nice
-    under some other set of formatting conventions.
+    <application>pgindent</> before the next release, so there's no point in
+    making it look nice under some other set of formatting conventions.
    </para>
 
    <para>