From 4b081371f4648830b5bcdd4c6e1ed1c12223ed3b Mon Sep 17 00:00:00 2001
From: Tom <25043847+Douile@users.noreply.github.com>
Date: Wed, 14 Jun 2023 20:25:26 +0000
Subject: [PATCH] [Crate] Add better documentation for generic game
 implementation (#49)

---
 src/games/mod.rs                 |  5 +++++
 src/lib.rs                       | 19 +++++++++++++++++--
 src/protocols/gamespy/mod.rs     |  2 ++
 src/protocols/minecraft/types.rs |  2 ++
 src/protocols/quake/types.rs     |  1 +
 src/protocols/valve/types.rs     |  1 +
 6 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/src/games/mod.rs b/src/games/mod.rs
index df0228e..6fa901e 100644
--- a/src/games/mod.rs
+++ b/src/games/mod.rs
@@ -116,11 +116,15 @@ use crate::protocols::{self, Protocol};
 use crate::GDResult;
 use std::net::{IpAddr, SocketAddr};
 
+/// Definition of a game
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[derive(Debug, Clone, PartialEq)]
 pub struct Game {
+    /// Full name of the game
     pub name: &'static str,
+    /// Default port used by game
     pub default_port: u16,
+    /// The protocol the game's query uses
     pub protocol: Protocol,
 }
 
@@ -130,6 +134,7 @@ mod definitions;
 #[cfg(feature = "game_defs")]
 pub use definitions::GAMES;
 
+/// Make a query given a game definition
 pub fn query(game: &Game, address: &IpAddr, port: Option<u16>) -> GDResult<protocols::GenericResponse> {
     let socket_addr = SocketAddr::new(*address, port.unwrap_or(game.default_port));
     Ok(match &game.protocol {
diff --git a/src/lib.rs b/src/lib.rs
index f14f090..1298415 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -2,6 +2,7 @@
 //!
 //! # Usage example:
 //!
+//! ## For a specific game
 //! ```
 //! use gamedig::games::tf2;
 //!
@@ -12,12 +13,26 @@
 //! }
 //! ```
 //!
+//! ## Using a game definition
+//! ```
+//! use gamedig::games::{GAMES, query};
+//!
+//! let game = GAMES.get("tf2").unwrap(); // Get a game definition, the full list can be found in src/games/mod.rs
+//! let response = query(game, &"127.0.0.1".parse().unwrap(), None); // None will use the default port
+//! match response {
+//!     Err(error) => println!("Couldn't query, error: {}", error),
+//!     Ok(r) => println!("{:#?}", r),
+//! }
+//! ```
+//!
 //! # Crate features:
-//! Enabled by default: None
+//! Enabled by default: `game_defs`
 //!
 //! `serde` - enables json serialization/deserialization for all response types.
 //! <br> `no_games` - disables the included games support. <br>
-//! `no_services` - disables the included services support.
+//! `no_services` - disables the included services support. <br>
+//! `game_defs` - Include game definitions for programmatic access (enabled by
+//! default).
 
 pub mod errors;
 #[cfg(not(feature = "no_games"))]
diff --git a/src/protocols/gamespy/mod.rs b/src/protocols/gamespy/mod.rs
index 0db17f3..648a419 100644
--- a/src/protocols/gamespy/mod.rs
+++ b/src/protocols/gamespy/mod.rs
@@ -7,6 +7,7 @@ pub mod protocols;
 
 pub use protocols::*;
 
+/// Versions of the gamespy protocol
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[derive(Debug, Clone, PartialEq)]
 pub enum GameSpyVersion {
@@ -15,6 +16,7 @@ pub enum GameSpyVersion {
     Three,
 }
 
+/// Enum of versions and their ExtraResponse data
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[derive(Debug, Clone, PartialEq)]
 pub enum VersionedExtraResponse {
diff --git a/src/protocols/minecraft/types.rs b/src/protocols/minecraft/types.rs
index 7bff98c..7600a99 100644
--- a/src/protocols/minecraft/types.rs
+++ b/src/protocols/minecraft/types.rs
@@ -78,6 +78,7 @@ pub struct JavaResponse {
     pub server_type: Server,
 }
 
+/// Non-generic java response
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
 pub struct JavaExtraResponse {
@@ -146,6 +147,7 @@ pub struct BedrockResponse {
     pub server_type: Server,
 }
 
+/// Non-generic bedrock response
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
 pub struct BedrockExtraResponse {
diff --git a/src/protocols/quake/types.rs b/src/protocols/quake/types.rs
index 15f47c7..3833704 100644
--- a/src/protocols/quake/types.rs
+++ b/src/protocols/quake/types.rs
@@ -24,6 +24,7 @@ pub struct Response<P> {
     pub unused_entries: HashMap<String, String>,
 }
 
+/// Non-generic quake response
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ExtraResponse {
diff --git a/src/protocols/valve/types.rs b/src/protocols/valve/types.rs
index 1392c3f..f3f7069 100644
--- a/src/protocols/valve/types.rs
+++ b/src/protocols/valve/types.rs
@@ -58,6 +58,7 @@ pub struct Response {
     pub rules: Option<HashMap<String, String>>,
 }
 
+/// Non-generic valve response
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[derive(Debug, Clone, PartialEq)]
 pub struct ExtraResponse {