From 490a9575424b3f15c1d82be47cdf82ac4470bdfc Mon Sep 17 00:00:00 2001
From: Richard Tjerngren <git@richodemus.com>
Date: Thu, 15 Apr 2021 00:16:39 +0000
Subject: [PATCH] Document Query.single() (#1915)

---
 crates/bevy_ecs/src/system/query.rs | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/crates/bevy_ecs/src/system/query.rs b/crates/bevy_ecs/src/system/query.rs
index 11d4ae2d45..d136f6f846 100644
--- a/crates/bevy_ecs/src/system/query.rs
+++ b/crates/bevy_ecs/src/system/query.rs
@@ -292,6 +292,33 @@ where
         }
     }
 
+    /// Gets the result of a single-result query
+    ///
+    /// If the query has exactly one result, returns the result inside `Ok`
+    /// otherwise returns either `Err(QuerySingleError::NoEntities(...))`
+    /// or `Err(QuerySingleError::MultipleEntities(...))`, as appropriate
+    ///
+    /// # Examples
+    ///
+    /// ```
+    ///  # use bevy_ecs::system::{Query, QuerySingleError};
+    ///  # use bevy_ecs::prelude::IntoSystem;
+    /// struct PlayerScore(i32);
+    /// fn player_scoring_system(query: Query<&PlayerScore>) {
+    ///     match query.single() {
+    ///         Ok(PlayerScore(score)) => {
+    ///             // do something with score
+    ///         }
+    ///         Err(QuerySingleError::NoEntities(_)) => {
+    ///             // no PlayerScore
+    ///         }
+    ///         Err(QuerySingleError::MultipleEntities(_)) => {
+    ///             // multiple PlayerScore
+    ///         }
+    ///     }
+    /// }
+    /// # let _check_that_its_a_system = player_scoring_system.system();
+    /// ```
     pub fn single(&self) -> Result<<Q::Fetch as Fetch<'_>>::Item, QuerySingleError>
     where
         Q::Fetch: ReadOnlyFetch,