Merge pull request #3216 from TylerMSFT/twhitney-noreturn

draft for noreturn

Author: megvanhuygen

docs/c-language/c-keywords.md

@@ -1,7 +1,7 @@
 ---
 title: "C Keywords"
 description: "Keywords in Standard C and Microsoft C compiler extensions."
-ms.date: 10/12/2020
+ms.date: 10/15/2020
 helpviewer_keywords: ["keywords [C]", "redefining keywords", "Microsoft-specific keywords"]
 ms.assetid: 2d932335-97bf-45cd-b367-4ae00db0ff42
 ---
@@ -121,7 +121,7 @@ The following keywords and special identifiers are recognized by the Microsoft C
 
 <sup>5</sup> For compatibility with previous versions, these keywords are available both with two leading underscores and a single leading underscore when Microsoft extensions are enabled.
 
-<sup>6</sup> When <assert.h> is not included, the Microsoft Visual C compiler maps **`static_assert`** to the C11 **`_Static_assert`** keyword.
+<sup>6</sup> If you don't include <assert.h>, the Microsoft Visual C compiler maps **`static_assert`** to the C11 **`_Static_assert`** keyword.
 
 Microsoft extensions are enabled by default. To assist in creating portable code, you can disable Microsoft extensions by specifying the [/Za \(Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md) option during compilation. When you use this option, some Microsoft-specific keywords are disabled.
 

docs/c-language/noreturn.md

@@ -0,0 +1,65 @@
+---
+title: "_Noreturn keyword and noreturn macro (C11)"
+description: "Describes the `_Noreturn` keyword and `noreturn` macro."
+ms.date: 10/16/2020
+f1_keywords: ["_Noreturn_c", "noreturn"]
+helpviewer_keywords: ["keywords [C]"]
+---
+
+# `_Noreturn` keyword and `noreturn` macro (C11)
+
+The `_Noreturn` keyword was introduced in C11. It tells the compiler that the function it's applied to doesn't return. The compiler knows that the code following a call to a `_Noreturn` function is unreachable.
+
+A convenience macro, `noreturn`, provided in <stdnoreturn.h>, maps to the `_Noreturn` keyword.
+
+The primary benefits for using `_Noreturn` (or the equivalent `noreturn`) are making the intention of the function clear in the code for future readers, and detecting unintentionally unreachable code.
+
+## Example using `noreturn` macro and `_Noreturn `keyword
+
+The following example demonstrates the `_Noreturn` keyword and the equivalent `noreturn` macro.
+
+IntelliSense may generate a spurious error, `E0065`, if you use the macro `noreturn` that you can ignore. It doesn't prevent you from running the sample.
+
+```C
+// Compile with Warning Level4 (/W4) and /std:c11
+#include <stdio.h>
+#include <stdlib.h>
+#include <stdnoreturn.h>
+
+noreturn void fatal_error(void)
+{
+    exit(3);
+}
+
+_Noreturn void not_coming_back(void)
+{
+    puts("There's no coming back");
+    fatal_error();
+    return; // warning C4645 - function declared with noreturn has a return statement
+}
+
+void done(void)
+{
+    puts("We'll never get here");
+}
+
+int main(void)
+{
+    not_coming_back();
+    done(); // warning c4702 - unreachable code
+
+    return 0;
+}
+```
+
+## Requirements
+
+|Macro|Required header|
+|-------------|---------------------|
+|**`noreturn`**|\<stdnoreturn.h>|
+
+## See also
+
+[/std (Specify language standard version)](../build/reference/std-specify-language-standard-version.md)\
+[/W4 (Specify warning level)](../build/reference/compiler-option-warning-level.md)
+[C4702 warning](../error-messages\compiler-warnings\compiler-warning-level-4-c4702.md)

docs/c-language/toc.yml

@@ -434,6 +434,8 @@
                 href: ../c-language/inline-functions.md
               - name: Inline assembler (C)
                 href: ../c-language/inline-assembler-c.md
+              - name: _Noreturn (C)
+                href: ../c-language/noreturn.md                
           - name: DLL import and export functions
             items: 
               - name: DLL import and export functions