docs: add crate-level documentation

README.md

@@ -49,7 +49,7 @@ println!("{ping_info:#?}, {latency:?}");
 
 ### Advanced API
 
-Elytra Ping can be customized for advanced usage by using the `SlpProtocol` API, which provides an interface for sending and receiving packets.
+Elytra Ping can be customized for advanced usage through the `SlpProtocol` API, which provides an interface for sending and receiving packets to and from Java Edition servers.
 
 ```rs
 let addrs = ("mc.hypixel.net".to_string(), 25565);
@@ -73,4 +73,4 @@ let status: String = match frame {
 println!("Status: {}", status);
 
 client.disconnect().await?;
-```
+```

src/lib.rs

@@ -1,3 +1,81 @@
+//! Through the `elytra_ping` crate, programs can retrieve the status and information about Minecraft Java Edition or Bedrock Edition servers.
+//!
+//! This crate can interact with servers running Minecraft Java 1.7+ or Bedrock. If you have the server's address and port, Elytra Ping can retrieve metadata like the server's description, player count, vendor, and icon. The (lack of the) server's response can also be used to infer whether it is online and usable or not.
+//!
+//! ## Usage
+//!
+//! Use the [`ping_or_timeout`] function to retrieve a Java Edition server's status and latency, aborting if it takes too long.
+//!
+//! ```
+//! # use std::time::Duration;
+//! # #[tokio::main]
+//! # async fn main() {
+//! let (ping_info, latency) = elytra_ping::ping_or_timeout(
+//!     ("mc.hypixel.net".to_string(), 25565),
+//!     Duration::from_secs(1),
+//! ).await.unwrap();
+//! println!("{ping_info:#?}, {latency:?}");
+//! # }
+//! ```
+//!
+//! Use the [`bedrock::ping`] function to retrieve a Bedrock Edition server's status and latency, specifying the number of retries
+//! if the operation fails initially and the amount of time to spend before timing out on a single retry.
+//!
+//! ```
+//! # use std::time::Duration;
+//! # #[tokio::main]
+//! # async fn main() {
+//! let retry_timeout = Duration::from_secs(2);
+//! let retries = 3;
+//! let (ping_info, latency) = elytra_ping::bedrock::ping(
+//!     ("play.cubecraft.net".to_string(), 19132),
+//!     retry_timeout,
+//!     retries,
+//! ).await.unwrap();
+//! println!("{ping_info:#?}, {latency:?}");
+//! // BedrockServerInfo {
+//! //     online_players: 10077,
+//! //     max_players: 55000,
+//! //     game_mode: Some(
+//! //         "Survival",
+//! //     ),
+//! //     ...
+//! // }, 83ms
+//! # }
+//! ```
+//!
+//! ### Advanced API
+//!
+//! Elytra Ping can be customized for advanced usage through the `SlpProtocol` API,
+//! which provides an interface for sending and receiving packets to and from Java Edition servers.
+//!
+//! ```
+//! # #[tokio::main]
+//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
+//! let addrs = ("mc.hypixel.net".to_string(), 25565);
+//! let mut client: elytra_ping::SlpProtocol = elytra_ping::connect(addrs).await?;
+//!
+//! // Set up our connection to receive a status packet
+//! client.handshake().await?;
+//! client.write_frame(elytra_ping::protocol::Frame::StatusRequest).await?;
+//!
+//! // Read the status packet from the server
+//! let frame: elytra_ping::protocol::Frame = client
+//!     .read_frame(None)
+//!     .await?
+//!     .expect("connection closed by server");
+//!
+//! let status: String = match frame {
+//!     elytra_ping::protocol::Frame::StatusResponse { json } => json,
+//!     _ => panic!("expected status packet"),
+//! };
+//!
+//! println!("Status: {}", status);
+//!
+//! client.disconnect().await?;
+//! # Ok(())
+//! # }
+//! ```
 use snafu::{Backtrace, Snafu};
 use std::time::Duration;