Documentation update

Cargo.toml

@@ -9,7 +9,7 @@ homepage = "https://github.com/CosminPerRam/rust-gamedig"
 documentation = "https://docs.rs/gamedig/latest/gamedig/"
 repository = "https://github.com/CosminPerRam/rust-gamedig"
 readme = "README.md"
-keywords = ["server", "valve", "games", "checker", "status"]
+keywords = ["server", "verify", "game", "check", "status"]
 
 [package.metadata]
 msrv = "1.58.1"

README.md

@@ -6,13 +6,10 @@ MSRV is `1.58.1` and the code is cross-platform.
 # Example
 Basic usage of the library is:
 ```rust
-use gamedig::TF2;
+use gamedig::games::tf2;
 
 fn main() {
-    let response = TF2::query("91.216.250.10", None);
+    let response = tf2::query("91.216.250.10", None); //or Some(27015), None is the default protocol port
-    //query your favorite game/protocol/service, some might come with different parameters
-    //here its just the IP and the port (if None, its gonna be the default from the protocol)
-    
     match response {
         Err(error) => println!("Couldn't query, error: {error}"),
         Ok(r) => println!("{:?}", r)
@@ -29,4 +26,4 @@ Curious about the history and what changed between versions? you can see just th
 To see the supported (or the planned to support) games, see [GAMES](GAMES.md).
 
 # Contributing
-If you want see your favorite game/service being supported here, open an issue (or do a pull request if you want to implement it yourself)!
+If you want see your favorite game/service being supported here, open an issue and I'll prioritize it! (or do a pull request if you want to implement it yourself)

examples/csgo.rs

@@ -1,8 +1,8 @@
 
-use gamedig::CSGO;
+use gamedig::games::csgo;
 
 fn main() {
-    let response = CSGO::query("51.38.142.109", None);
+    let response = csgo::query("51.38.142.109", None);
     match response {
         Err(error) => println!("Couldn't query, error: {error}"),
         Ok(r) => println!("{:?}", r)

examples/tf2.rs

@@ -1,8 +1,8 @@
 
-use gamedig::TF2;
+use gamedig::games::tf2;
 
 fn main() {
-    let response = TF2::query("91.216.250.10", None);
+    let response = tf2::query("91.216.250.10", None); //or Some(27015), None is the default protocol port
     match response {
         Err(error) => println!("Couldn't query, error: {error}"),
         Ok(r) => println!("{:?}", r)

examples/the_ship.rs

@@ -1,8 +1,8 @@
 
-use gamedig::TheShip;
+use gamedig::games::the_ship;
 
 fn main() {
-    let response = TheShip::query("46.4.48.226", Some(27017));
+    let response = the_ship::query("46.4.48.226", Some(27017));
     match response {
         Err(error) => println!("Couldn't query, error: {error}"),
         Ok(r) => println!("{:?}", r)

src/errors.rs

@@ -1,14 +1,22 @@
 use core::fmt;
 use std::fmt::Formatter;
 
+/// GameDigError, every error you can encounter using the library.
 #[derive(Debug, Clone)]
 pub enum GDError {
+    /// The received packet was bigger than the buffer size.
     PacketOverflow(String),
+    /// The received packet was shorter than the expected one.
     PacketUnderflow(String),
+    /// The received packet was badly formatted.
     PacketBad(String),
+    /// Couldn't send the packet.
     PacketSend(String),
+    /// Couldn't send the receive.
     PacketReceive(String),
+    /// Unknown cast while translating a value to an enum
     UnknownEnumCast,
+    /// The server queried is not from the queried game.
     BadGame(String)
 }
 

src/games/csgo.rs

@@ -1,9 +1,6 @@
 use crate::errors::GDError;
 use crate::valve::{ValveProtocol, App, GatheringSettings, Response};
 
-pub struct CSGO;
-
-impl CSGO {
 pub fn query(address: &str, port: Option<u16>) -> Result<Response, GDError> {
     ValveProtocol::query(App::CSGO, address, match port {
         None => 27015,
@@ -13,4 +10,3 @@ impl CSGO {
         rules: true
     })
 }
-}

src/games/mod.rs

@@ -1,8 +1,6 @@
 
+//! Currently supported games.
+
 pub mod tf2;
 pub mod the_ship;
 pub mod csgo;
-
-pub use tf2::*;
-pub use the_ship::*;
-pub use csgo::*;

src/games/tf2.rs

@@ -1,9 +1,6 @@
 use crate::errors::GDError;
 use crate::valve::{ValveProtocol, App, GatheringSettings, Response};
 
-pub struct TF2;
-
-impl TF2 {
 pub fn query(address: &str, port: Option<u16>) -> Result<Response, GDError> {
     ValveProtocol::query(App::TF2, address, match port {
         None => 27015,
@@ -13,4 +10,3 @@ impl TF2 {
         rules: true
     })
 }
-}

src/games/the_ship.rs

@@ -1,9 +1,6 @@
 use crate::errors::GDError;
 use crate::valve::{ValveProtocol, App, GatheringSettings, Response};
 
-pub struct TheShip;
-
-impl TheShip {
 pub fn query(address: &str, port: Option<u16>) -> Result<Response, GDError> {
     ValveProtocol::query(App::TheShip, address, match port {
         None => 27015,
@@ -13,4 +10,3 @@ impl TheShip {
         rules: true
     })
 }
-}

src/lib.rs

@@ -1,8 +1,24 @@
 
+//! Query many servers
+//!
+//! # Example
+//!
+//! ```no_run
+//! use gamedig::games::tf2;
+//!
+//! fn main() {
+//!     let response = tf2::query("91.216.250.10", None); //or Some(27015), None is the default protocol port
+//!     match response {
+//!         Err(error) => println!("Couldn't query, error: {error}"),
+//!         Ok(r) => println!("{:?}", r)
+//!     }
+//! }
+//! ```
+
 pub mod errors;
 pub mod protocols;
-mod utils;
 pub mod games;
+mod utils;
 
 pub use errors::*;
 pub use protocols::*;

src/protocols/mod.rs

@@ -1,2 +1,8 @@
 
+//! Protocols that are currently implemented.
+//!
+//! A protocol will be here if it supports multiple entries, if not, its implementation will be
+//! in that specific needed place, a protocol can be independently queried.
+
+/// Reference: [Server Query](https://developer.valvesoftware.com/wiki/Server_queries)
 pub mod valve;

src/protocols/valve.rs

@@ -3,6 +3,7 @@ use std::net::UdpSocket;
 use crate::errors::GDError;
 use crate::utils::{buffer, complete_address, concat_u8_arrays};
 
+/// The type of the server.
 #[derive(Debug)]
 pub enum Server {
     Dedicated,
@@ -10,6 +11,7 @@ pub enum Server {
     SourceTV
 }
 
+/// The Operating System that the server is on.
 #[derive(Debug)]
 pub enum Environment {
     Linux,
@@ -17,6 +19,7 @@ pub enum Environment {
     Mac
 }
 
+/// A query response.
 #[derive(Debug)]
 pub struct Response {
     pub info: ServerInfo,
@@ -24,47 +27,73 @@ pub struct Response {
     pub rules: Option<ServerRules>
 }
 
+/// General server information's.
 #[derive(Debug)]
 pub struct ServerInfo {
+    /// Protocol used by the server.
     pub protocol: u8,
-    pub map: String,
+    /// Name of the server.
     pub name: String,
+    /// Map name.
+    pub map: String,
+    /// Name of the folder containing the game files.
     pub folder: String,
+    /// Full name of the game.
     pub game: String,
+    /// [Steam Application ID](https://developer.valvesoftware.com/wiki/Steam_Application_ID) of game.
     pub id: u16,
+    /// Number of players on the server.
     pub players: u8,
+    /// Maximum number of players the server reports it can hold.
     pub max_players: u8,
+    /// Number of bots on the server.
     pub bots: u8,
+    /// Dedicated, NonDedicated or SourceTV
     pub server_type: Server,
+    /// The Operating System that the server is on.
     pub environment_type: Environment,
+    /// Indicated whether the server requires a password.
     pub has_password: bool,
+    /// Indicated whether the server uses VAC.
     pub vac_secured: bool,
+    /// [The ship](https://developer.valvesoftware.com/wiki/The_Ship) extra data
     pub the_ship: Option<TheShip>,
+    /// Version of the game installed on the server.
     pub version: String,
+    /// Some extra data that the server might provide or not.
     pub extra_data: Option<ExtraData>
 }
 
+/// Server's players.
 #[derive(Debug)]
 pub struct ServerPlayers {
     pub count: u8,
     pub players: Vec<Player>
 }
 
+/// Data about a player
 #[derive(Debug)]
 pub struct Player {
+    /// Player's name.
     pub name: String,
+    /// General score.
     pub score: u32,
+    /// How long they've been on the server for.
     pub duration: f32,
+    /// Only for [the ship](https://developer.valvesoftware.com/wiki/The_Ship): deaths count
     pub deaths: Option<u32>, //the_ship
+    /// Only for [the ship](https://developer.valvesoftware.com/wiki/The_Ship): money amount
     pub money: Option<u32>, //the_ship
 }
 
+/// Server's rules.
 #[derive(Debug)]
 pub struct ServerRules {
     pub count: u16,
     pub map: HashMap<String, String>
 }
 
+/// Only present for [the ship](https://developer.valvesoftware.com/wiki/The_Ship).
 #[derive(Debug)]
 pub struct TheShip {
     pub mode: u8,
@@ -72,23 +101,35 @@ pub struct TheShip {
     pub duration: u8
 }
 
+/// Some extra data that the server might provide or not.
 #[derive(Debug)]
 pub struct ExtraData {
+    /// The server's game port number.
     pub port: Option<u16>,
+    /// Server's SteamID.
     pub steam_id: Option<u64>,
+    /// Spectator port number for SourceTV.
     pub tv_port: Option<u16>,
+    /// Name of the spectator server for SourceTV.
     pub tv_name: Option<String>,
+    /// Tags that describe the game according to the server.
     pub keywords: Option<String>,
+    /// The server's 64-bit GameID.
     pub game_id: Option<u64>
 }
 
+/// The type of the request, see the [protocol](https://developer.valvesoftware.com/wiki/Server_queries).
 #[derive(PartialEq)]
 pub enum Request {
+    /// Known as `A2S_INFO`
     INFO,
+    /// Known as `A2S_PLAYERS`
     PLAYERS,
+    /// Known as `A2S_RULES`
     RULES
 }
 
+/// Supported app id's
 #[derive(PartialEq)]
 pub enum App {
     TF2 = 440,
@@ -109,6 +150,7 @@ impl TryFrom<u16> for App {
     }
 }
 
+/// What data to gather, purely used only with the query function.
 pub struct GatheringSettings {
     pub players: bool,
     pub rules: bool
@@ -152,6 +194,7 @@ impl ValveProtocol {
         Ok(final_packet)
     }
 
+    /// Ask for a specific request only.
     pub fn get_request_data(&self, app: &App, kind: Request) -> Result<Vec<u8>, GDError> {
         let info_initial_packet = vec![0xFF, 0xFF, 0xFF, 0xFF, 0x54, 0x53, 0x6F, 0x75, 0x72, 0x63, 0x65, 0x20, 0x45, 0x6E, 0x67, 0x69, 0x6E, 0x65, 0x20, 0x51, 0x75, 0x65, 0x72, 0x79, 0x00];
         let players_initial_packet = vec![0xFF, 0xFF, 0xFF, 0xFF, 0x55, 0xFF, 0xFF, 0xFF, 0xFF];
@@ -191,7 +234,8 @@ impl ValveProtocol {
         }
     }
 
-    fn get_server_info(&self, app: &App) -> Result<ServerInfo, GDError> {
+    /// Get the server information's.
+    pub fn get_server_info(&self, app: &App) -> Result<ServerInfo, GDError> {
         let buf = self.get_request_data(app, Request::INFO)?;
         let mut pos = 0;
 
@@ -260,7 +304,8 @@ impl ValveProtocol {
         })
     }
 
-    fn get_server_players(&self, app: &App) -> Result<ServerPlayers, GDError> {
+    /// Get the server player's.
+    pub fn get_server_players(&self, app: &App) -> Result<ServerPlayers, GDError> {
         let buf = self.get_request_data(app, Request::PLAYERS)?;
         let mut pos = 0;
 
@@ -290,7 +335,8 @@ impl ValveProtocol {
         })
     }
 
-    fn get_server_rules(&self, app: &App) -> Result<Option<ServerRules>, GDError> {
+    /// Get the server rules's.
+    pub fn get_server_rules(&self, app: &App) -> Result<Option<ServerRules>, GDError> {
         if *app == App::CSGO { //cause csgo response here is broken after feb 21 2014
             return Ok(None);
         }