[3/4] Documentation/process: Add fallthrough pseudo-keyword
diff mbox series

Message ID 09a42c7275afa7e6e9e3fc57a15122201fccd6f7.1570292505.git.joe@perches.com
State New, archived
Headers show
Series
  • treewide: Add 'fallthrough' pseudo-keyword
Related show

Commit Message

Joe Perches Oct. 5, 2019, 4:46 p.m. UTC
Describe the fallthrough pseudo-keyword.

Convert the coding-style.rst example to the keyword style.
Add description and links to deprecated.rst.

Signed-off-by: Joe Perches <joe@perches.com>
---
 Documentation/process/coding-style.rst |  2 +-
 Documentation/process/deprecated.rst   | 33 +++++++++++++++++++++++----------
 2 files changed, 24 insertions(+), 11 deletions(-)

Comments

Miguel Ojeda Oct. 5, 2019, 5:47 p.m. UTC | #1
On Sat, Oct 5, 2019 at 6:47 PM Joe Perches <joe@perches.com> wrote:
>
> diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst
> index 56280e108d5a..a0ffdc8daef3 100644
> --- a/Documentation/process/deprecated.rst
> +++ b/Documentation/process/deprecated.rst
> @@ -122,14 +122,27 @@ memory adjacent to the stack (when built without `CONFIG_VMAP_STACK=y`)
>
>  Implicit switch case fall-through
>  ---------------------------------
> -The C language allows switch cases to "fall through" when
> -a "break" statement is missing at the end of a case. This,
> -however, introduces ambiguity in the code, as it's not always
> -clear if the missing break is intentional or a bug. As there
> -have been a long list of flaws `due to missing "break" statements
> +The C language allows switch cases to "fall-through" when a "break" statement
> +is missing at the end of a case. This, however, introduces ambiguity in the
> +code, as it's not always clear if the missing break is intentional or a bug.
> +
> +As there have been a long list of flaws `due to missing "break" statements
>  <https://cwe.mitre.org/data/definitions/484.html>`_, we no longer allow
> -"implicit fall-through". In order to identify an intentional fall-through
> -case, we have adopted the marking used by static analyzers: a comment
> -saying `/* Fall through */`. Once the C++17 `__attribute__((fallthrough))`
> -is more widely handled by C compilers, static analyzers, and IDEs, we can
> -switch to using that instead.
> +"implicit fall-through".
> +
> +In order to identify intentional fall-through cases, we have adopted a
> +pseudo-keyword macro 'fallthrough' which expands to gcc's extension
> +__attribute__((__fallthrough__)).  `Statement Attributes
> +<https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html>`_
> +
> +When the C17/C18  [[fallthrough]] syntax is more commonly supported by

Note that C17/C18 does not have [[fallthrough]]. C++17 introduced it,
as it is mentioned above. I would keep the
__attribute__((fallthrough)) -> [[fallthrough]] change you did,
though, since that is indeed the standard syntax (given the paragraph
references C++17).

I was told by Aaron Ballman (who is proposing them for C) that it is
more or less likely that it becomes standardized in C2x. However, it
is still not added to the draft (other attributes are already,
though). See N2268 and N2269:

    http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2268.pdf (fallthrough)
    http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2269.pdf
(attributes in general)

Cheers,
Miguel
Nick Desaulniers Oct. 9, 2019, 9:51 p.m. UTC | #2
On Sat, Oct 5, 2019 at 10:48 AM Miguel Ojeda
<miguel.ojeda.sandonis@gmail.com> wrote:
>
> On Sat, Oct 5, 2019 at 6:47 PM Joe Perches <joe@perches.com> wrote:
> >
> > +When the C17/C18  [[fallthrough]] syntax is more commonly supported by
>
> Note that C17/C18 does not have [[fallthrough]]. C++17 introduced it,
> as it is mentioned above. I would keep the
> __attribute__((fallthrough)) -> [[fallthrough]] change you did,
> though, since that is indeed the standard syntax (given the paragraph
> references C++17).
>
> I was told by Aaron Ballman (who is proposing them for C) that it is
> more or less likely that it becomes standardized in C2x. However, it
> is still not added to the draft (other attributes are already,
> though). See N2268 and N2269:
>
>     http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2268.pdf (fallthrough)
>     http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2269.pdf
> (attributes in general)
>

Interesting. I think those links might be useful to include, or drop
the section on C++ style attributes outright. Either way:
Acked-by: Nick Desaulniers <ndesaulniers@google.com>

Patch
diff mbox series

diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index f4a2198187f9..ada573b7d703 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -56,7 +56,7 @@  instead of ``double-indenting`` the ``case`` labels.  E.g.:
 	case 'K':
 	case 'k':
 		mem <<= 10;
-		/* fall through */
+		fallthrough;
 	default:
 		break;
 	}
diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst
index 56280e108d5a..a0ffdc8daef3 100644
--- a/Documentation/process/deprecated.rst
+++ b/Documentation/process/deprecated.rst
@@ -122,14 +122,27 @@  memory adjacent to the stack (when built without `CONFIG_VMAP_STACK=y`)
 
 Implicit switch case fall-through
 ---------------------------------
-The C language allows switch cases to "fall through" when
-a "break" statement is missing at the end of a case. This,
-however, introduces ambiguity in the code, as it's not always
-clear if the missing break is intentional or a bug. As there
-have been a long list of flaws `due to missing "break" statements
+The C language allows switch cases to "fall-through" when a "break" statement
+is missing at the end of a case. This, however, introduces ambiguity in the
+code, as it's not always clear if the missing break is intentional or a bug.
+
+As there have been a long list of flaws `due to missing "break" statements
 <https://cwe.mitre.org/data/definitions/484.html>`_, we no longer allow
-"implicit fall-through". In order to identify an intentional fall-through
-case, we have adopted the marking used by static analyzers: a comment
-saying `/* Fall through */`. Once the C++17 `__attribute__((fallthrough))`
-is more widely handled by C compilers, static analyzers, and IDEs, we can
-switch to using that instead.
+"implicit fall-through".
+
+In order to identify intentional fall-through cases, we have adopted a
+pseudo-keyword macro 'fallthrough' which expands to gcc's extension
+__attribute__((__fallthrough__)).  `Statement Attributes
+<https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html>`_
+
+When the C17/C18  [[fallthrough]] syntax is more commonly supported by
+C compilers, static analyzers, and IDEs, we can switch to using that syntax
+for the macro pseudo-keyword.
+
+All switch/case blocks must end in one of:
+
+	break;
+	fallthrough;
+	continue;
+	goto <label>;
+	return [expression];