authorgravatar for kappaloris@gmail.comLoris Cro <kappaloris@gmail.com> 2025-02-15 18:04:29+01:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2025-02-26 14:41:33-05:00
log06a66745a0b5c666608482645bc61523618dab85
tree6b699b0241cc02f89a27c0b241eb58857dec87d4
parentba7cd8121d5a52beb1e9844a784ec7a439ee6cfd

`@deprecated`: add langref entry

2 files changed, 59 insertions(+), 0 deletions(-)

doc/langref.html.in+37
...@@ -4740,6 +4740,43 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val...@@ -4740,6 +4740,43 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
4740 </p>4740 </p>
4741 {#see_also|@cVaArg|@cVaCopy|@cVaEnd#}4741 {#see_also|@cVaArg|@cVaCopy|@cVaEnd#}
4742 {#header_close#}4742 {#header_close#}
4743
4744 {#header_open|@deprecated#}
4745 <pre>{#syntax#}@deprecated(value: anytype) @TypeOf(value){#endsyntax#}</pre>
4746 <pre>{#syntax#}@deprecated() void{#endsyntax#}</pre>
4747 <p>
4748 Used to mark a given code path as deprecated. It evaluates to the same value
4749 passed in as argument, or the {#syntax#}void{#endsyntax#} value when given none.
4750 </p>
4751 <p>
4752 As an example, in Zig 0.14.0 {#syntax#}std.time.sleep{#endsyntax#} was
4753 deprecated and the sleep function was moved to {#syntax#}std.Thread.sleep{#endsyntax#}.
4754 This is how this deprecation could have been expressed:
4755
4756 {#syntax_block|zig|lib/std/time.zig#}
4757pub const sleep = @deprecated(std.Thread.sleep); // moved
4758 {#end_syntax_block#}
4759 </p>
4760 <p>
4761 By default it is a <b>compile error</b> to depend on deprecated code in
4762 a module defined by the root package, while it is not in modules defined
4763 by dependencies. This behavior can be overridden for the entire dependency
4764 tree by passing {#syntax#}-fallow-deprecated{#endsyntax#} or
4765 {#syntax#}-fno-allow-deprecated{#endsyntax#} to {#syntax#}zig build{#endsyntax#}.
4766 </p>
4767 <p>
4768 Usage of this builtin is meant to help <i>direct</i> consumers discover (and remove)
4769 their dependance on deprecated code during the grace period before a deprecated
4770 functionality is turned into a {#syntax#}@compileError{#endsyntax#} or
4771 removed entirely.
4772 </p>
4773
4774 <p>
4775 {#syntax#}@deprecated{#endsyntax#} can also be used without argument:
4776 {#code|test_deprecated_builtin.zig#}
4777 </p>
4778
4779 {#header_close#}
47434780
4744 {#header_open|@divExact#}4781 {#header_open|@divExact#}
4745 <pre>{#syntax#}@divExact(numerator: T, denominator: T) T{#endsyntax#}</pre>4782 <pre>{#syntax#}@divExact(numerator: T, denominator: T) T{#endsyntax#}</pre>
doc/langref/test_deprecated_builtin.zig created+22
...@@ -0,0 +1,22 @@
1test "deprecated code path" {
2 compute(.greedy, false, 42);
3}
4
5const Strategy = enum { greedy, expensive, fast };
6fn compute(comptime strat: Strategy, comptime foo: bool, bar: usize) void {
7 switch (strat) {
8 .greedy => {
9 // This combination turned out to be ineffective.
10 if (!foo) @deprecated(); // use fast strategy when foo is false
11 runGreedy(foo, bar);
12 },
13 .expensive => runExpensive(foo, bar),
14 .fast => runFast(foo, bar),
15 }
16}
17
18extern fn runGreedy(foo: bool, bar: usize) void;
19extern fn runExpensive(foo: bool, bar: usize) void;
20extern fn runFast(foo: bool, bar: usize) void;
21
22// test_error=deprecated