docs: Improve some ComponentId doc cross-linking. (#9839)

# Objective

- When reading API docs and seeing a reference to `ComponentId`, it
isn't immediately clear how to get one from your `Component`. It could
be made to be more clear.

## Solution

- Improve cross-linking of docs about `ComponentId`
This commit is contained in:
Bruce Mitchener 2023-09-19 04:42:04 +07:00 committed by GitHub
parent 5e91e5f3ce
commit 444245106e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 38 additions and 4 deletions

View file

@ -282,6 +282,10 @@ impl ComponentInfo {
/// A `ComponentId` is tightly coupled to its parent `World`. Attempting to use a `ComponentId` from
/// one `World` to access the metadata of a `Component` in a different `World` is undefined behavior
/// and must not be attempted.
///
/// Given a type `T` which implements [`Component`], the `ComponentId` for `T` can be retrieved
/// from a `World` using [`World::component_id()`] or via [`Components::component_id()`]. Access
/// to the `ComponentId` for a [`Resource`] is available via [`Components::resource_id()`].
#[derive(Debug, Copy, Clone, Hash, Ord, PartialOrd, Eq, PartialEq)]
pub struct ComponentId(usize);
@ -442,6 +446,11 @@ impl Components {
/// Initializes a component of type `T` with this instance.
/// If a component of this type has already been initialized, this will return
/// the ID of the pre-existing component.
///
/// # See also
///
/// * [`Components::component_id()`]
/// * [`Components::init_component_with_descriptor()`]
#[inline]
pub fn init_component<T: Component>(&mut self, storages: &mut Storages) -> ComponentId {
let type_id = TypeId::of::<T>();
@ -463,6 +472,11 @@ impl Components {
///
/// If this method is called multiple times with identical descriptors, a distinct `ComponentId`
/// will be created for each one.
///
/// # See also
///
/// * [`Components::component_id()`]
/// * [`Components::init_component()`]
pub fn init_component_with_descriptor(
&mut self,
storages: &mut Storages,
@ -525,7 +539,7 @@ impl Components {
self.components.get_unchecked(id.0)
}
/// Type-erased equivalent of [`Components::component_id`].
/// Type-erased equivalent of [`Components::component_id()`].
#[inline]
pub fn get_id(&self, type_id: TypeId) -> Option<ComponentId> {
self.indices.get(&type_id).map(|index| ComponentId(*index))
@ -538,7 +552,7 @@ impl Components {
/// instance.
///
/// Returns [`None`] if the `Component` type has not
/// yet been initialized using [`Components::init_component`].
/// yet been initialized using [`Components::init_component()`].
///
/// ```rust
/// use bevy_ecs::prelude::*;
@ -552,12 +566,18 @@ impl Components {
///
/// assert_eq!(component_a_id, world.components().component_id::<ComponentA>().unwrap())
/// ```
///
/// # See also
///
/// * [`Components::get_id()`]
/// * [`Components::resource_id()`]
/// * [`World::component_id()`]
#[inline]
pub fn component_id<T: Component>(&self) -> Option<ComponentId> {
self.get_id(TypeId::of::<T>())
}
/// Type-erased equivalent of [`Components::resource_id`].
/// Type-erased equivalent of [`Components::resource_id()`].
#[inline]
pub fn get_resource_id(&self, type_id: TypeId) -> Option<ComponentId> {
self.resource_indices
@ -572,7 +592,7 @@ impl Components {
/// instance.
///
/// Returns [`None`] if the `Resource` type has not
/// yet been initialized using [`Components::init_resource`].
/// yet been initialized using [`Components::init_resource()`].
///
/// ```rust
/// use bevy_ecs::prelude::*;
@ -586,6 +606,11 @@ impl Components {
///
/// assert_eq!(resource_a_id, world.components().resource_id::<ResourceA>().unwrap())
/// ```
///
/// # See also
///
/// * [`Components::component_id()`]
/// * [`Components::get_resource_id()`]
#[inline]
pub fn resource_id<T: Resource>(&self) -> Option<ComponentId> {
self.get_resource_id(TypeId::of::<T>())
@ -594,6 +619,10 @@ impl Components {
/// Initializes a [`Resource`] of type `T` with this instance.
/// If a resource of this type has already been initialized, this will return
/// the ID of the pre-existing resource.
///
/// # See also
///
/// * [`Components::resource_id()`]
#[inline]
pub fn init_resource<T: Resource>(&mut self) -> ComponentId {
// SAFETY: The [`ComponentDescriptor`] matches the [`TypeId`]

View file

@ -219,6 +219,11 @@ impl World {
///
/// assert_eq!(component_a_id, world.component_id::<ComponentA>().unwrap())
/// ```
///
/// # See also
///
/// * [`Components::component_id()`]
/// * [`Components::get_id()`]
#[inline]
pub fn component_id<T: Component>(&self) -> Option<ComponentId> {
self.components.component_id::<T>()