langref: improve the defer section

Split the original `defer.zig` doctest into 3 doctest:

  1. Document the defer keyword
  2. Document that the return statement is not allowed inside a defer
     expression
  3. Document the errdefer keyword

Replace "method" with "expression" in the text `defer method`.

1 files changed, 14 insertions, 13 deletions

diff --git a/doc/langref.html.in b/doc/langref.html.in
index c8830b796c..2809dd6122 100644
--- a/doc/langref.html.in
+++ b/doc/langref.html.in
@@ -4959,6 +4959,20 @@ fn deferUnwindExample() void {
 test "defer unwinding" {
     deferUnwindExample();
 }
+      {#code_end#}
+      {#code_begin|test_err|cannot return from defer expression#}
+// Inside a defer expression the return statement is not allowed.
+fn deferInvalidExample() !void {
+    defer {
+        return error.DeferError;
+    }
+
+    return error.DeferError;
+}
+      {#code_end#}
+      {#code_begin|test|errdefer#}
+const std = @import("std");
+const print = std.debug.print;
 
 // The errdefer keyword is similar to defer, but will only execute if the
 // scope returns with an error.
@@ -4977,19 +4991,6 @@ fn deferErrorExample(is_error: bool) !void {
         print("encountered an error!\n", .{});
     }
 
-    // inside a defer method the return statement
-    // is not allowed.
-    // The following lines produce the following
-    // error if uncomment
-    // ```
-    // defer.zig:73:9: error: cannot return from defer expression
-    // return error.DeferError;
-    // ```
-    //
-    //defer {
-    //    return error.DeferError;
-    //}
-
     if (is_error) {
         return error.DeferError;
     }