Add #[deprecated(since = "0.16.0", ...)] to items missing it (#18702)

- The `#[deprecated]` attributes supports a `since` field, which
documents in which version an item was deprecated. This field is visible
in `rustdoc`.
- We inconsistently use `since` throughout the project.

For an example of what `since` renders as, take a look at
`ChildOf::get()`:

```rust
/// The parent entity of this child entity.
pub fn get(&self) -> Entity {
    self.0
}
```

![image](https://github.com/user-attachments/assets/2ea5d8c9-2eab-430a-9a1c-421f315ff123)

- Add `since = "0.16.0"` to all `#[deprecated]` attributes that do not
already use it.
- Add an example of deprecating a struct with the `since` field in the
migration guide document.

I would appreciate if this could be included in 0.16's release, as its a
low-risk documentation improvement that is valuable for the release, but
I'd understand if this was cut.

You can use `cargo doc` to inspect the rendered form of
`#[deprecated(since = "0.16.0", ...)]`.
This commit is contained in:
BD103 2025-04-03 13:06:01 -04:00 committed by François Mockers
parent c9fb956058
commit 0b3a51bd7e
4 changed files with 19 additions and 5 deletions

View File

@ -150,7 +150,10 @@ impl<T: Asset> Clone for Handle<T> {
impl<A: Asset> Handle<A> {
/// Create a new [`Handle::Weak`] with the given [`u128`] encoding of a [`Uuid`].
#[deprecated = "use the `weak_handle!` macro with a UUID string instead"]
#[deprecated(
since = "0.16.0",
note = "use the `weak_handle!` macro with a UUID string instead"
)]
pub const fn weak_from_u128(value: u128) -> Self {
Handle::Weak(AssetId::Uuid {
uuid: Uuid::from_u128(value),

View File

@ -244,6 +244,7 @@ impl Hash for Entity {
}
#[deprecated(
since = "0.16.0",
note = "This is exclusively used with the now deprecated `Entities::alloc_at_without_replacement`."
)]
pub(crate) enum AllocAtWithoutReplacement {
@ -694,6 +695,7 @@ impl Entities {
/// Returns the location of the entity currently using the given ID, if any. Location should be
/// written immediately.
#[deprecated(
since = "0.16.0",
note = "This can cause extreme performance problems when used after freeing a large number of entities and requesting an arbitrary entity. See #18054 on GitHub."
)]
pub fn alloc_at(&mut self, entity: Entity) -> Option<EntityLocation> {
@ -728,6 +730,7 @@ impl Entities {
///
/// Returns the location of the entity currently using the given ID, if any.
#[deprecated(
since = "0.16.0",
note = "This can cause extreme performance problems when used after freeing a large number of entities and requesting an arbitrary entity. See #18054 on GitHub."
)]
#[expect(

View File

@ -1532,7 +1532,10 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> {
/// - [`get_many`](Self::get_many) for the non-panicking version.
#[inline]
#[track_caller]
#[deprecated(note = "Use `get_many` instead and handle the Result.")]
#[deprecated(
since = "0.16.0",
note = "Use `get_many` instead and handle the Result."
)]
pub fn many<const N: usize>(&self, entities: [Entity; N]) -> [ROQueryItem<'_, D>; N] {
match self.get_many(entities) {
Ok(items) => items,
@ -1929,7 +1932,10 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> {
/// - [`many`](Self::many) to get read-only query items.
#[inline]
#[track_caller]
#[deprecated(note = "Use `get_many_mut` instead and handle the Result.")]
#[deprecated(
since = "0.16.0",
note = "Use `get_many_mut` instead and handle the Result."
)]
pub fn many_mut<const N: usize>(&mut self, entities: [Entity; N]) -> [D::Item<'_>; N] {
match self.get_many_mut(entities) {
Ok(items) => items,
@ -1993,7 +1999,7 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> {
}
/// A deprecated alias for [`single`](Self::single).
#[deprecated(note = "Please use `single` instead")]
#[deprecated(since = "0.16.0", note = "Please use `single` instead")]
pub fn get_single(&self) -> Result<ROQueryItem<'_, D>, QuerySingleError> {
self.single()
}
@ -2028,7 +2034,7 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> {
}
/// A deprecated alias for [`single_mut`](Self::single_mut).
#[deprecated(note = "Please use `single_mut` instead")]
#[deprecated(since = "0.16.0", note = "Please use `single_mut` instead")]
pub fn get_single_mut(&mut self) -> Result<D::Item<'_>, QuerySingleError> {
self.single_mut()
}

View File

@ -2253,6 +2253,7 @@ impl World {
/// ```
#[track_caller]
#[deprecated(
since = "0.16.0",
note = "This can cause extreme performance problems when used with lots of arbitrary free entities. See #18054 on GitHub."
)]
pub fn insert_or_spawn_batch<I, B>(&mut self, iter: I) -> Result<(), Vec<Entity>>
@ -2272,6 +2273,7 @@ impl World {
/// as a command.
#[inline]
#[deprecated(
since = "0.16.0",
note = "This can cause extreme performance problems when used with lots of arbitrary free entities. See #18054 on GitHub."
)]
pub(crate) fn insert_or_spawn_batch_with_caller<I, B>(