add nearest_entity_by and improve some docs

3 files changed, 50 insertions, 14 deletions

diff --git a/azalea-client/src/account.rs b/azalea-client/src/account.rs
index 7e3f917d..bda69558 100644
--- a/azalea-client/src/account.rs
+++ b/azalea-client/src/account.rs
@@ -22,8 +22,8 @@ use uuid::Uuid;
 /// # Examples
 ///
 /// ```rust,no_run
-/// use azalea_client::Account;
-///
+/// # use azalea_client::Account;
+/// #
 /// # #[tokio::main]
 /// # async fn main() {
 /// let account = Account::microsoft("example@example.com").await;
diff --git a/azalea-client/src/entity_query.rs b/azalea-client/src/entity_query.rs
index ee99d0f4..49119b98 100644
--- a/azalea-client/src/entity_query.rs
+++ b/azalea-client/src/entity_query.rs
@@ -36,15 +36,16 @@ impl Client {
             })
     }
 
-    /// Return a lightweight [`Entity`] for an arbitrary entity that matches the
-    /// given predicate function that is in the same [`Instance`] as the
-    /// client.
+    /// Quickly returns a lightweight [`Entity`] for an arbitrary entity that
+    /// matches the given predicate function that is in the same
+    /// [`Instance`] as the client.
     ///
     /// You can then use [`Self::entity_component`] to get components from this
     /// entity.
     ///
-    /// Also see [`Self::entities_by`] which will return all entities that match
-    /// the predicate and sorts them by distance (unlike `entity_by`).
+    /// If you want to find the nearest entity, consider using
+    /// [`Self::nearest_entity_by`] instead. If you want to find all entities
+    /// that match the predicate, use [`Self::nearest_entities_by`].
     ///
     /// # Example
     /// ```
@@ -65,7 +66,7 @@ impl Client {
     ///
     /// [`Entity`]: bevy_ecs::entity::Entity
     /// [`Instance`]: azalea_world::Instance
-    pub fn entity_by<F: QueryFilter, Q: QueryData>(
+    pub fn any_entity_by<F: QueryFilter, Q: QueryData>(
         &self,
         predicate: impl EntityPredicate<Q, F>,
     ) -> Option<Entity> {
@@ -73,12 +74,47 @@ impl Client {
         predicate.find_any(self.ecs.clone(), &instance_name)
     }
 
-    /// Similar to [`Self::entity_by`] but returns a `Vec<Entity>` of all
-    /// entities in our instance that match the predicate.
+    /// Return a lightweight [`Entity`] for the nearest entity that matches the
+    /// given predicate function.
     ///
-    /// Unlike `entity_by`, the result is sorted by distance to our client's
-    /// position, so the closest entity is first.
-    pub fn entities_by<F: QueryFilter, Q: QueryData>(
+    /// You can then use [`Self::entity_component`] to get components from this
+    /// entity.
+    ///
+    /// If you don't need the entity to be the nearest one, it may be more
+    /// efficient to use [`Self::any_entity_by`] instead. You can also use
+    /// [`Self::nearest_entities_by`] to get all nearby entities.
+    ///
+    /// # Example
+    /// ```
+    /// use azalea_entity::{Position, metadata::Player, LocalEntity};
+    /// use bevy_ecs::query::With;
+    ///
+    /// # fn example(mut bot: azalea_client::Client, sender_name: String) {
+    /// // look at the nearest player
+    /// if let Some(closest_player) = bot
+    ///     .entities_by::<(With<Player>, Without<LocalEntity>), ()>(|_: &()| true)
+    ///     .first()
+    /// {
+    ///     let closest_player_pos = *bot.entity_component::<Position>(*closest_player);
+    ///     bot.look_at(closest_player_pos.up(1.62));
+    /// }
+    /// }
+    /// ```
+    ///
+    /// [`Entity`]: bevy_ecs::entity::Entity
+    /// [`Instance`]: azalea_world::Instance
+    pub fn nearest_entity_by<F: QueryFilter, Q: QueryData>(
+        &self,
+        predicate: impl EntityPredicate<Q, F>,
+    ) -> Option<Entity> {
+        self.nearest_entities_by(predicate).first().copied()
+    }
+
+    /// Similar to [`Self::nearest_entity_by`] but returns a `Vec<Entity>` of
+    /// all entities in our instance that match the predicate.
+    ///
+    /// The first entity is the nearest one.
+    pub fn nearest_entities_by<F: QueryFilter, Q: QueryData>(
         &self,
         predicate: impl EntityPredicate<Q, F>,
     ) -> Vec<Entity> {
diff --git a/azalea-client/src/plugins/movement.rs b/azalea-client/src/plugins/movement.rs
index c27a67ce..675796f6 100644
--- a/azalea-client/src/plugins/movement.rs
+++ b/azalea-client/src/plugins/movement.rs
@@ -452,7 +452,7 @@ impl Client {
     }
 
     /// Start sprinting in the given direction. To stop moving, call
-    /// [`Client::walk(WalkDirection::None)`]
+    /// [`bot.walk(WalkDirection::None)`](Self::walk)
     ///
     /// # Examples
     ///