Repository: diesel-rs/diesel
File: diesel/src/associations/belongs_to.rs (Rust)

Code before:
///
/// **Child** refers to the "many" part of a "one to many" relationship. It "belongs to" its parent
/// **Parent** refers to the "one" part of a "one to many" relationship and can "have many" children.
/// The child always has a foreign key, which refers to its parent's primary key.
/// In the following relationship, User has many Posts,
/// so User is the parent and Posts are children.
///
/// # Unrelated Rows
///
/// When using [`GroupedBy::grouped_by`], if the child rows were not queried
/// using the provided parent rows, it is not guaranteed a parent row
/// will be found for a given child row.
/// This is possible, if the foreign key in the relationship is nullable,
/// or if a child row's parent was not present in the provided slice,
/// in which case, unrelated child rows will be discarded.
///
/// If discarding these rows is undesirable, it may be preferable to use
/// [`GroupedBy::try_grouped_by`].
///
/// # Handling Duplicate Parent Rows
///
/// Both [`GroupedBy::grouped_by`] and [`GroupedBy::try_grouped_by`]
/// expect all of the elements of `parents` to produce a unique value
/// when calling [`Identifiable::id`].
/// If this is not true, child rows will be grouped against the last row
/// that produced a given ID.
///
/// This behaviour should typically be a result of `parents` containing
/// duplicates of one or more rows.
/// This may happen if parents rows are selected based on a join query,
/// as a copy of the parent row will be retrieved
/// for each child row they were joined with.
///
/// As a result, it is recommended to add [`QueryDsl::distinct`]
/// to queries that may exhibit this behaviour,
/// or use [`Vec::sort`] and [`Vec::dedup`] on the loaded rows,
/// to ensure the elements of `parents` are unique.
///
/// # Example
///
/// ```rust
/// # include!("../doctest_setup.rs");
/// # use schema::{posts, users};
/// #
/// # #[derive(Identifiable, Queryable, PartialEq, Debug)]
/// # pub struct User {
/// #     id: i32,
/// #     name: String,
/// # }
/// #
/// # #[derive(Debug, PartialEq)]

Review comment (suggestion):
I wouldn't document which item gets the child rows so that we can change the implementation of the function later.

Code after:
///
/// **Child** refers to the "many" part of a "one to many" relationship. It "belongs to" its parent
/// **Parent** refers to the "one" part of a "one to many" relationship and can "have many" children.
/// The child always has a foreign key, which refers to its parent's primary key.
/// In the following relationship, User has many Posts,
/// so User is the parent and Posts are children.
///
/// # Unrelated Rows
///
/// When using [`GroupedBy::grouped_by`], if the child rows were not queried
/// using the provided parent rows, it is not guaranteed a parent row
/// will be found for a given child row.
/// This is possible, if the foreign key in the relationship is nullable,
/// or if a child row's parent was not present in the provided slice,
/// in which case, unrelated child rows will be discarded.
///
/// If discarding these rows is undesirable, it may be preferable to use
/// [`GroupedBy::try_grouped_by`].
///
/// # Handling Duplicate Parent Rows
///
/// Both [`GroupedBy::grouped_by`] and [`GroupedBy::try_grouped_by`]
/// expect all of the elements of `parents` to produce a unique value
/// when calling [`Identifiable::id`].
/// If this is not true, child rows may be added to an unexpected index.
///
/// As a result, it is recommended to use [`QueryDsl::distinct`]
/// or [`slice::sort`] and [`Vec::dedup`],
/// to ensure the elements of `parents` are unique.
///
/// # Example
///
/// ```rust
/// # include!("../doctest_setup.rs");
/// # use schema::{posts, users};
/// #
/// # #[derive(Identifiable, Queryable, PartialEq, Debug)]
/// # pub struct User {
/// #     id: i32,
/// #     name: String,
/// # }
/// #
/// # #[derive(Debug, PartialEq)]
/// # #[derive(Identifiable, Queryable, Associations)]
/// # #[diesel(belongs_to(User))]
/// # pub struct Post {
/// #     id: i32,
/// #     user_id: i32,
/// #     title: String,
/// # }
/// #