From f270bef9a4d21e880826cef6b5264acdc84f0a6f Mon Sep 17 00:00:00 2001
From: Mathieu Guay-Paquet <mathieu.guaypaquet@gmail.com>
Date: Fri, 2 Apr 2021 14:57:42 -0400
Subject: [PATCH] docs: document the nosuspend keyword (#7972)

* docs: document the nosuspend keyword

* Specify that resuming from suspend is allowed in nosuspend

* Fix the description of the requirements of nosuspend

* Make use of nosuspend in some example code.

This is mainly motivated by the incorrect claim that "there would be
no way to collect the return value of amain, if it were something
other than void".
---
 doc/langref.html.in | 23 ++++++++++++++---------
 1 file changed, 14 insertions(+), 9 deletions(-)

diff --git a/doc/langref.html.in b/doc/langref.html.in
index dc18c0a069..9aa106fb54 100644
--- a/doc/langref.html.in
+++ b/doc/langref.html.in
@@ -6594,13 +6594,11 @@ const std = @import("std");
 const expect = std.testing.expect;
 
 test "async and await" {
-    // Here we have an exception where we do not match an async
-    // with an await. The test block is not async and so cannot
-    // have a suspend point in it.
-    // This is well-defined behavior, and everything is OK here.
-    // Note however that there would be no way to collect the
-    // return value of amain, if it were something other than void.
-    _ = async amain();
+    // The test block is not async and so cannot have a suspend
+    // point in it. By using the nosuspend keyword, we promise that
+    // the code in amain will finish executing without suspending
+    // back to the test block.
+    nosuspend amain();
 }
 
 fn amain() void {
@@ -10799,9 +10797,16 @@ fn readU32Be() u32 {}
             <pre>{#syntax#}nosuspend{#endsyntax#}</pre>
           </td>
           <td>
-            The {#syntax#}nosuspend{#endsyntax#} keyword.
+            The {#syntax#}nosuspend{#endsyntax#} keyword can be used in front of a block, statement or expression, to mark a scope where no suspension points are reached.
+            In particular, inside a {#syntax#}nosuspend{#endsyntax#} scope:
             <ul>
-              <li>TODO add documentation for nosuspend</li>
+              <li>Using the {#syntax#}suspend{#endsyntax#} keyword results in a compile error.</li>
+              <li>Using {#syntax#}await{#endsyntax#} on a function frame which hasn't completed yet results in safety-checked {#link|Undefined Behavior#}.</li>
+              <li>Calling an async function may result in safety-checked {#link|Undefined Behavior#}, because it's equivalent to <code>await async some_async_fn()</code>, which contains an {#syntax#}await{#endsyntax#}.</li>
+            </ul>
+            Code inside a {#syntax#}nosuspend{#endsyntax#} scope does not cause the enclosing function to become an {#link|async function|Async Functions#}.
+            <ul>
+              <li>See also {#link|Async Functions#}</li>
             </ul>
           </td>
         </tr>