htdocs/gcc-6/porting_to.html is looking rather empty right now. The attached patch starts fleshing it out by adding some notes on -Wmisleading-indentation.
[see the notes at https://gcc.gnu.org/ml/gcc/2016-01/msg00224.html on what -Wmisleading-indentation ran into on a mass-rebuild of Debian] I put it apart from the existing headings as it relates to both C and to C++. Validates. OK to commit? Dave
Index: htdocs/gcc-6/porting_to.html =================================================================== RCS file: /cvs/gcc/wwwdocs/htdocs/gcc-6/porting_to.html,v retrieving revision 1.1 diff -u -p -r1.1 porting_to.html --- htdocs/gcc-6/porting_to.html 20 Jan 2016 11:53:52 -0000 1.1 +++ htdocs/gcc-6/porting_to.html 26 Jan 2016 20:35:05 -0000 @@ -33,6 +33,69 @@ manner. Additions and suggestions for im <h2>C++ language issues</h2> +<h2>-Wmisleading-indentation</h2> +<p> +A new warning <code>-Wmisleading-indentation</code> was added +to <code>-Wall</code>, warning about places where the indentation of +the code might mislead a human reader about the control flow: +</p> + +<blockquote><pre> +<b>sslKeyExchange.c:</b> In function <b>'SSLVerifySignedServerKeyExchange'</b>: +<b>sslKeyExchange.c:631:8:</b> <span class="boldmagenta">warning:</span> statement is indented as if it were guarded by... [<span class="boldmagenta">-Wmisleading-indentation</span>] + <span class="boldmagenta">goto</span> fail; + <span class="boldmagenta">^~~~</span> +<b>sslKeyExchange.c:629:4:</b> <span class="boldcyan">note:</span> ...this 'if' clause, but it is not + <span class="boldcyan">if</span> ((err = SSLHashSHA1.update(&hashCtx, &signedParams)) != 0) + <span class="boldcyan">^~</span> +</pre></blockquote> + +<p> +This has highlighted genuine bugs, often due to missing braces, but it +sometimes reports warnings for poorly-indented files, or on projects +with unusual indentation. This may cause build errors if you +have <code>-Wall -Werror</code> in your project. +</p> + +<p> +The best fix is usually to fix the indentation of the code to match +the block structure, or to fix the block structure by adding missing +braces. If changing the source is not practical or desirable (e.g. for +autogenerated code, or to avoid churn in the source history), the +warning can be disabled by adding <code>-Wno-misleading-indentation</code> +to the build flags. Alternatively, you can disable it for just one part of +a source file or function using pragmas: +</p> + +<pre><code> +#pragma GCC diagnostic push +#pragma GCC diagnostic ignored "-Wmisleading-indentation" + +/* (code for which the warning is to be disabled) */ + +#pragma GCC diagnostic pop +</code></pre> + +<p> +Source files with mixed tabs and spaces that don't use 8-space tabs +may lead to warnings. A real-world example was for such a source file, which +contained an Emacs directive to view tabs to be 4 spaces wide: +</p> + +<blockquote><pre> + /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +</pre></blockquote> + +<p> +The mixture of tabs and spaces did correctly reflect the block +structure when viewed in Emacs, but not in other editors, or in an +HTML view of the source repository. +By default, <code>-Wmisleading-indentation</code> assumes tabs to +be 8 spaces wide. It would have been possible to avoid this warning +by adding <code>-ftabstop=4</code> to the build flags for this file, +but given that the code was confusing when viewed in other editors, +the indentation of the source was fixed instead. +</p> <h3>Links</h3>
