mirrors/zig
1
0
Fork 0
mirror of https://codeberg.org/ziglang/zig.git synced 2025-12-06 05:44:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

langref: update deprecated section

Browse source
This commit is contained in:
Andrew Kelley 2025-02-25 23:02:24 -08:00
parent 7c2649f89d
commit 4ddb13468b
1 changed files with 17 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

34
doc/langref.html.in
View file

@ -4745,36 +4745,36 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
<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 void value when given none.
Marks a given code path as scheduled for removal. Evaluates to the same
value passed in as argument, or the {#syntax#}void{#endsyntax#} value
when given none.
</p>
<p>
As an example, a library that wishes to move or rename a declaration, while
deprecating usage of the old name can use {#syntax#}@deprecated{#endsyntax#} like so:
When a public declaration has been moved to a new location, the old
location can be marked {#syntax#}@deprecated{#endsyntax#}:
</p>
{#syntax_block|zig|root.zig#}
pub const fooToBar = @deprecated(bar.fromFoo); // moved
{#end_syntax_block#}
<p>
By default it is a <b>compile error</b> to reference 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#}.
By default deprecated code paths are disallowed in a module defined by
the root package but allowed in modules defined by the rest of the
dependency tree. This behavior can be overridden by passing
<code>-fallow-deprecated</code> or <code>-fno-allow-deprecated</code> to
<code>zig build</code>.
</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.
The purpose of {#syntax#}@deprecated{#endsyntax#} is to provide at least
one version (a "grace period") of a package that supports both old and new APIs
simultaneously, while providing tooling for programmers to discover what needs
to be upgraded to migrate to the new API. Such a grace period has the key property
that it allows a project's dependency tree to be upgraded <em>one package at a time</em>.
</p>
<p>
Using {#syntax#}@deprecated{#endsyntax#} without an argument can be useful inside of blocks:
Using {#syntax#}@deprecated{#endsyntax#} without an argument can be
useful inside of conditionally compiled blocks:
</p>
{#code|test_deprecated_builtin.zig#}
{#header_close#}
{#header_open|@divExact#}