From 667dc33249fc2f0d215bdd60d74ca891ea39a033 Mon Sep 17 00:00:00 2001
From: Katalina Okano <git@kat.cafe>
Date: Sun, 27 Nov 2022 18:41:35 -0500
Subject: [PATCH] add some docs

---
 services/api/src/health.rs | 13 +++++++++++++
 services/api/src/query.rs  |  6 ++++++
 services/api/src/world.rs  |  7 ++++++-
 3 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/services/api/src/health.rs b/services/api/src/health.rs
index 718447f..5564d23 100644
--- a/services/api/src/health.rs
+++ b/services/api/src/health.rs
@@ -38,35 +38,48 @@ pub async fn get_health(
 
 #[derive(Enum, Copy, Clone, Eq, PartialEq)]
 enum UpDown {
+    /// The service is up and running
     Up,
+
+    /// The service is down
     Down,
 }
 
 #[derive(Enum, Copy, Clone, Eq, PartialEq)]
 enum WebsocketState {
+    /// The Nanite Systems manifold is sending events, and the primary listener is processing data.
     Primary,
+
+    /// The Daybreak Games manifold is sending events, and the backup listener is processing data; the primary listener is down.
     Backup,
+
+    /// The entire event streaming system is down.
     Down,
 }
 
 pub struct Health {}
 
+/// Reports on the health of Saerro Listening Post
 #[Object]
 impl Health {
+    /// Did a ping to Redis (our main datastore) succeed?
     async fn redis(&self) -> UpDown {
         UpDown::Up
     }
 
+    /// What is the state of the websocket listener cluster for PC?
     #[graphql(name = "pc")]
     async fn pc(&self) -> WebsocketState {
         WebsocketState::Primary
     }
 
+    /// What is the state of the websocket listener cluster for PS4 US?
     #[graphql(name = "ps4us")]
     async fn ps4us(&self) -> WebsocketState {
         WebsocketState::Primary
     }
 
+    /// What is the state of the websocket listener cluster for PS4 EU?
     #[graphql(name = "ps4eu")]
     async fn ps4eu(&self) -> WebsocketState {
         WebsocketState::Primary
diff --git a/services/api/src/query.rs b/services/api/src/query.rs
index acb362f..7e1bdee 100644
--- a/services/api/src/query.rs
+++ b/services/api/src/query.rs
@@ -6,18 +6,24 @@ pub struct Query;
 
 #[Object]
 impl Query {
+    /// Returns a graph for the world with the given ID.
+    /// If the world does not exist, this will not fail.
     async fn world(&self, id: String) -> World {
         World { id: id.clone() }
     }
 
+    /// Returns a graph for the world specified by it's human name.
+    /// This is case-insensitive; but will not fail.
     async fn world_by_name(&self, name: String) -> World {
         World::from_name(name)
     }
 
+    /// Returns a graph of all known live play worlds.
     async fn all_worlds(&self) -> Vec<World> {
         World::all_worlds()
     }
 
+    /// Reports on the health of Saerro Listening Post
     async fn health(&self) -> Health {
         Health {}
     }
diff --git a/services/api/src/world.rs b/services/api/src/world.rs
index 4881911..76d749b 100644
--- a/services/api/src/world.rs
+++ b/services/api/src/world.rs
@@ -26,7 +26,6 @@ lazy_static! {
         ("2000", "Ceres"),
     ]);
 }
-
 pub struct World {
     pub id: String,
 }
@@ -48,6 +47,12 @@ impl World {
     }
 }
 
+/// **A PlanetSide 2 world.**
+///
+/// This can be fetched at the top level with `world(id: "1")` or `worldByName(name: "Connery")`.
+/// ...or get all of them with `allWorlds`.
+///
+/// If World.id is not valid or known to the API, World.name will return "Unknown".
 #[Object]
 impl World {
     async fn id(&self) -> &str {