From ab38b610011cdb66afbfcc95a79f2d6db44edce8 Mon Sep 17 00:00:00 2001
From: krunchington <krunchington@gmail.com>
Date: Fri, 7 Mar 2025 15:32:43 -0800
Subject: [PATCH] Update Component docs to point to Relationship trait (#18179)

also updates Relationship docs terminology

# Objective

- Contributes to #18111

## Solution

Updates Component docs with a new section linking to Relationship. Also
updates some Relationship terminology as I understand it.

## Testing

- Did you test these changes? If so, how?
  - opened Docs, verified link
- Are there any parts that need more testing?
  - I don't think so
- How can other people (reviewers) test your changes? Is there anything
specific they need to know?
- run `cargo doc --open` and check out Component and Relationship docs,
verify their correctness
- If relevant, what platforms did you test these changes on, and are
there any important ones you can't test?
  - I think this is n/a but I ran the doc command on Ubuntu 24.04.2 LTS

---

## Showcase


![image](https://github.com/user-attachments/assets/241eecb2-dd98-43ab-875a-1a3ec1176a79)


## Migration Guide

n/a
---
 crates/bevy_ecs/src/component.rs        | 17 +++++++++++++++++
 crates/bevy_ecs/src/relationship/mod.rs |  2 +-
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/crates/bevy_ecs/src/component.rs b/crates/bevy_ecs/src/component.rs
index fb72de9cec..fcc009e451 100644
--- a/crates/bevy_ecs/src/component.rs
+++ b/crates/bevy_ecs/src/component.rs
@@ -282,6 +282,23 @@ use thiserror::Error;
 /// Note that requirements must currently be registered before the requiring component is inserted
 /// into the world for the first time. Registering requirements after this will lead to a panic.
 ///
+/// # Relationships between Entities
+///
+/// Sometimes it is useful to define relationships between entities.  A common example is the
+/// parent / child relationship. Since Components are how data is stored for Entities, one might
+/// naturally think to create a Component which has a field of type [`Entity`].
+///
+/// To facilitate this pattern, Bevy provides the [`Relationship`](`crate::relationship::Relationship`)
+/// trait. You can derive the [`Relationship`](`crate::relationship::Relationship`) and
+/// [`RelationshipTarget`](`crate::relationship::RelationshipTarget`) traits in addition to the
+/// Component trait in order to implement data driven relationships between entities, see the trait
+/// docs for more details.
+///
+/// In addition, Bevy provides canonical implementations of the parent / child relationship via the
+/// [`ChildOf`](crate::hierarchy::ChildOf) [`Relationship`](crate::relationship::Relationship) and
+/// the [`Children`](crate::hierarchy::Children)
+/// [`RelationshipTarget`](crate::relationship::RelationshipTarget).
+///
 /// # Adding component's hooks
 ///
 /// See [`ComponentHooks`] for a detailed explanation of component's hooks.
diff --git a/crates/bevy_ecs/src/relationship/mod.rs b/crates/bevy_ecs/src/relationship/mod.rs
index e7f35240bd..3072c78c10 100644
--- a/crates/bevy_ecs/src/relationship/mod.rs
+++ b/crates/bevy_ecs/src/relationship/mod.rs
@@ -50,7 +50,7 @@ use log::warn;
 /// #[relationship(relationship_target = Children)]
 /// pub struct ChildOf {
 ///     #[relationship]
-///     pub child: Entity,
+///     pub parent: Entity,
 ///     internal: u8,
 /// };
 ///