[llvm-branch-commits] [llvm-branch] r164493 - /llvm/branches/R600/docs/CodingStandards.rst

[Tom Stellard]

Author: tstellar
Date: Mon Sep 24 10:51:24 2012
New Revision: 164493

URL: http://llvm.org/viewvc/llvm-project?rev=164493&view=rev
Log:
Document "do not use defaults in covered switch-over-enum" coding standard.

Modified:
    llvm/branches/R600/docs/CodingStandards.rst

Modified: llvm/branches/R600/docs/CodingStandards.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/branches/R600/docs/CodingStandards.rst?rev=164493&r1=164492&r2=164493&view=diff
==============================================================================
--- llvm/branches/R600/docs/CodingStandards.rst (original)
+++ llvm/branches/R600/docs/CodingStandards.rst Mon Sep 24 10:51:24 2012
@@ -818,6 +818,24 @@
 will copy the vtable and RTTI into every ``.o`` file that ``#include``\s the
 header, bloating ``.o`` file sizes and increasing link times.
 
+Don't use default labels in fully covered switches over enumerations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``-Wswitch`` warns if a switch, without a default label, over an enumeration
+does not cover every enumeration value. If you write a default label on a fully
+covered switch over an enumeration then the ``-Wswitch`` warning won't fire
+when new elements are added to that enumeration. To help avoid adding these
+kinds of defaults, Clang has the warning ``-Wcovered-switch-default`` which is
+off by default but turned on when building LLVM with a version of Clang that
+supports the warning.
+
+A knock-on effect of this stylistic requirement is that when building LLVM with
+GCC you may get warnings related "control may reach end of non-void function"
+if you return from each case of a covered switch-over-enum because GCC assumes
+that the enum expression may take any representable value, not just those in
+the enumeration. To suppress this warning, use ``llvm_unreachable`` after the
+switch.
+
 Use ``LLVM_DELETED_FUNCTION`` to mark uncallable methods
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^