@deprecated: add langref entry

doc/langref.html.in

@@ -4741,6 +4741,43 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
       {#see_also|@cVaArg|@cVaCopy|@cVaEnd#}
       {#header_close#}
 	
+      {#header_open|@deprecated#}
+      <pre>{#syntax#}@deprecated(value: anytype) @TypeOf(value){#endsyntax#}</pre>
+      <pre>{#syntax#}@deprecated() void{#endsyntax#}</pre>
+      <p>
+	  Used to mark a given code path as deprecated. It evaluates to the same value
+	  passed in as argument, or the {#syntax#}void{#endsyntax#} value when given none.
+      </p>
+      <p>
+      As an example, in Zig 0.14.0 {#syntax#}std.time.sleep{#endsyntax#} was
+	  deprecated and the sleep function was moved to {#syntax#}std.Thread.sleep{#endsyntax#}.
+	  This is how this deprecation could have been expressed:
+	   
+      {#syntax_block|zig|lib/std/time.zig#}
+pub const sleep = @deprecated(std.Thread.sleep); // moved
+      {#end_syntax_block#}
+	  </p>
+      <p>
+      By default it is a <b>compile error</b> to depend on deprecated code in
+	  a module defined by the root package, while it is not in modules defined
+	  by dependencies. This behavior can be overridden for the entire dependency
+	  tree by passing {#syntax#}-fallow-deprecated{#endsyntax#} or
+	  {#syntax#}-fno-allow-deprecated{#endsyntax#} to {#syntax#}zig build{#endsyntax#}.
+      </p>
+      <p>
+	  Usage of this builtin is meant to help <i>direct</i> consumers discover (and remove)
+	  their dependance on deprecated code during the grace period before a deprecated
+	  functionality is turned into a {#syntax#}@compileError{#endsyntax#} or
+	  removed entirely.   
+      </p>
+
+	  <p>
+      {#syntax#}@deprecated{#endsyntax#} can also be used without argument: 	
+      {#code|test_deprecated_builtin.zig#}
+	  </p>
+	
+      {#header_close#}
+
       {#header_open|@divExact#}
       <pre>{#syntax#}@divExact(numerator: T, denominator: T) T{#endsyntax#}</pre>
       <p>

doc/langref/test_deprecated_builtin.zig

@@ -0,0 +1,22 @@
+test "deprecated code path" {
+    compute(.greedy, false, 42);
+}
+
+const Strategy = enum { greedy, expensive, fast };
+fn compute(comptime strat: Strategy, comptime foo: bool, bar: usize) void {
+    switch (strat) {
+        .greedy => {
+            // This combination turned out to be ineffective.
+            if (!foo) @deprecated(); // use fast strategy when foo is false
+            runGreedy(foo, bar);
+        },
+        .expensive => runExpensive(foo, bar),
+        .fast => runFast(foo, bar),
+    }
+}
+
+extern fn runGreedy(foo: bool, bar: usize) void;
+extern fn runExpensive(foo: bool, bar: usize) void;
+extern fn runFast(foo: bool, bar: usize) void;
+
+// test_error=deprecated