Commit 4ddb13468b372b2f722703b5e6d60997776c251a | zig

author	Andrew Kelley <andrew@ziglang.org> 2025-02-25 23:02:24-08:00
committer	Andrew Kelley <andrew@ziglang.org> 2025-02-26 14:41:33-05:00
log	4ddb13468b372b2f722703b5e6d60997776c251a
tree	6ba0e654c4496af02efd22f6dd0e069d9677030e
parent	7c2649f89dc76afca46c3aa5c675719b647cdd10

langref: update deprecated section

1 files changed, 17 insertions(+), 17 deletions(-)

doc
- langref.html.in

doc/langref.html.in+17-17

 @@ -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
+      Marks a given code path as scheduled for removal. Evaluates to the same
-      passed in as argument, or the void value when given none.
+      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
+      When a public declaration has been moved to a new location, the old
-      deprecating usage of the old name can use {#syntax#}@deprecated{#endsyntax#} like so:
+      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
+      By default deprecated code paths are disallowed in a module defined by
-      a module defined by the root package, while it is not in modules defined
+      the root package but allowed in modules defined by the rest of the
-      by dependencies. This behavior can be overridden for the entire dependency
+      dependency tree. This behavior can be overridden by passing
-      tree by passing {#syntax#}-fallow-deprecated{#endsyntax#} or
+      <code>-fallow-deprecated</code> or <code>-fno-allow-deprecated</code> to
-      {#syntax#}-fno-allow-deprecated{#endsyntax#} to {#syntax#}zig build{#endsyntax#}.
+      <code>zig build</code>.
       </p>
       <p>
-      Usage of this builtin is meant to help <i>direct</i> consumers discover (and remove)
+      The purpose of {#syntax#}@deprecated{#endsyntax#} is to provide at least
-      their dependance on deprecated code during the grace period before a deprecated
+      one version (a "grace period") of a package that supports both old and new APIs
-      functionality is turned into a {#syntax#}@compileError{#endsyntax#} or
+      simultaneously, while providing tooling for programmers to discover what needs
-      removed entirely.
+      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#}