diff --git a/azalea-auth/README.md b/azalea-auth/README.md index aa290c94..568a9f88 100755 --- a/azalea-auth/README.md +++ b/azalea-auth/README.md @@ -2,4 +2,26 @@ A port of Mojang's Authlib and launcher authentication. +# Examples + +``` +use std::path::PathBuf; + +#[tokio::main] +async fn main() { + let cache_file = PathBuf::from("example_cache.json"); + + let auth_result = azalea_auth::auth( + "example@example.com", + azalea_auth::AuthOpts { + cache_file: Some(cache_file), + ..Default::default() + }, + ) + .await + .unwrap(); + println!("{auth_result:?}"); +} +``` + Thanks to [wiki.vg contributors](https://wiki.vg/Microsoft_Authentication_Scheme), [Overhash](https://gist.github.com/OverHash/a71b32846612ba09d8f79c9d775bfadf), and [prismarine-auth contributors](https://github.com/PrismarineJS/prismarine-auth). diff --git a/azalea-auth/src/lib.rs b/azalea-auth/src/lib.rs index 17c87636..794332d4 100755 --- a/azalea-auth/src/lib.rs +++ b/azalea-auth/src/lib.rs @@ -1,3 +1,5 @@ +#![doc = include_str!("../README.md")] + mod auth; mod cache; pub mod game_profile; diff --git a/azalea-block/azalea-block-macros/src/lib.rs b/azalea-block/azalea-block-macros/src/lib.rs index 4f750383..8b26122c 100755 --- a/azalea-block/azalea-block-macros/src/lib.rs +++ b/azalea-block/azalea-block-macros/src/lib.rs @@ -1,3 +1,5 @@ +//! An internal crate used by `azalea_block`. + mod utils; use proc_macro::TokenStream; diff --git a/azalea-block/src/lib.rs b/azalea-block/src/lib.rs index 685aed92..6d45fbf4 100755 --- a/azalea-block/src/lib.rs +++ b/azalea-block/src/lib.rs @@ -1,3 +1,5 @@ +#![doc = include_str!("../README.md")] + mod behavior; mod blocks; diff --git a/azalea-brigadier/README.md b/azalea-brigadier/README.md index a7318566..c5aff629 100755 --- a/azalea-brigadier/README.md +++ b/azalea-brigadier/README.md @@ -1,3 +1,7 @@ # Azalea Brigadier A Rust port of Mojang's [Brigadier](https://github.com/Mojang/brigadier) command parsing and dispatching library. + +# Examples + +See the [tests](https://github.com/mat-1/azalea/tree/main/azalea-brigadier/tests). diff --git a/azalea-brigadier/src/lib.rs b/azalea-brigadier/src/lib.rs index cf2ce571..eb670643 100755 --- a/azalea-brigadier/src/lib.rs +++ b/azalea-brigadier/src/lib.rs @@ -1,3 +1,5 @@ +#![doc = include_str!("../README.md")] + pub mod arguments; pub mod builder; pub mod command_dispatcher; diff --git a/azalea-buf/README.md b/azalea-buf/README.md index cfb701ff..378f3e05 100755 --- a/azalea-buf/README.md +++ b/azalea-buf/README.md @@ -2,4 +2,4 @@ An implementation of Minecraft's FriendlyByteBuf. This is used frequently in the game for serialization and deserialization of data. -Note that there are some minor implementation differences such as using unsigned integers in places where Minecraft uses signed integers. This doesn't cause issues normally, but does technically make usage of azalea-buf detectable if a server really wants to since it won't error in places where vanilla Minecraft would. +Note that there are some minor implementation differences such as using unsigned integers in places where Minecraft uses signed integers. This doesn't cause issues normally, but does technically make usage of azalea-buf detectable if a server really wants to since it won't error in places where vanilla Minecraft would. diff --git a/azalea-buf/src/lib.rs b/azalea-buf/src/lib.rs index 73d76949..abdf2a3b 100755 --- a/azalea-buf/src/lib.rs +++ b/azalea-buf/src/lib.rs @@ -1,5 +1,4 @@ -//! Utilities for reading and writing for the Minecraft protocol - +#![doc = include_str!("../README.md")] #![feature(min_specialization)] // these two are necessary for thiserror backtraces #![feature(error_generic_member_access)] diff --git a/azalea-chat/README.md b/azalea-chat/README.md index 2bc9d418..1cf52878 100755 --- a/azalea-chat/README.md +++ b/azalea-chat/README.md @@ -1,3 +1,23 @@ # Azalea Chat -Parse Minecraft chat messages. +Things for working with Minecraft formatted text components. + +# Examples + +``` +// convert a Minecraft component JSON into colored text that can be printed to the terminal. + +use azalea_chat::Component; +use serde_json::Value; +use serde::Deserialize; + +let j: Value = serde_json::from_str( + r#"{"text": "hello","color": "red","bold": true}"# +) +.unwrap(); +let component = Component::deserialize(&j).unwrap(); +assert_eq!( + component.to_ansi(), + "\u{1b}[1m\u{1b}[38;2;255;85;85mhello\u{1b}[m" +); +``` diff --git a/azalea-chat/src/lib.rs b/azalea-chat/src/lib.rs index fd26ee4f..97a2580d 100755 --- a/azalea-chat/src/lib.rs +++ b/azalea-chat/src/lib.rs @@ -1,5 +1,4 @@ -//! Things for working with Minecraft chat messages. -//! This was inspired by Minecraft and prismarine-chat. +#![doc = include_str!("../README.md")] pub mod base_component; mod component; diff --git a/azalea-core/README.md b/azalea-core/README.md index 7d826076..f8564484 100755 --- a/azalea-core/README.md +++ b/azalea-core/README.md @@ -1,3 +1,3 @@ # Azalea Core -Miscellaneous things in Azalea. +Random miscellaneous things like `bitsets` and `Vec3` that don't deserve their own crate. diff --git a/azalea-core/src/lib.rs b/azalea-core/src/lib.rs index 30af2448..198189bd 100755 --- a/azalea-core/src/lib.rs +++ b/azalea-core/src/lib.rs @@ -1,5 +1,4 @@ -//! Random miscellaneous things like UUIDs that don't deserve their own crate. - +#![doc = include_str!("../README.md")] #![feature(int_roundings)] #![allow(incomplete_features)] #![feature(generic_const_exprs)] diff --git a/azalea-crypto/src/lib.rs b/azalea-crypto/src/lib.rs index 9b223f96..cefc9adc 100755 --- a/azalea-crypto/src/lib.rs +++ b/azalea-crypto/src/lib.rs @@ -1,3 +1,5 @@ +#![doc = include_str!("../README.md")] + mod signing; use aes::cipher::inout::InOutBuf; diff --git a/azalea-language/README.md b/azalea-language/README.md index c971832c..87453cf3 100755 --- a/azalea-language/README.md +++ b/azalea-language/README.md @@ -2,3 +2,8 @@ Translate Minecraft strings from their id. +# Examples + +``` +assert_eq!(azalea_language::get("translation.test.none"), Some("Hello, world!")); +``` \ No newline at end of file diff --git a/azalea-language/src/lib.rs b/azalea-language/src/lib.rs index 81c3cee2..ad9da43a 100755 --- a/azalea-language/src/lib.rs +++ b/azalea-language/src/lib.rs @@ -1,4 +1,4 @@ -//! Translate Minecraft strings from their id. +#![doc = include_str!("../README.md")] use once_cell::sync::Lazy; use std::collections::HashMap; @@ -9,13 +9,3 @@ pub static STORAGE: Lazy> = pub fn get(key: &str) -> Option<&str> { STORAGE.get(key).map(|s| s.as_str()) } - -#[cfg(test)] -mod tests { - use super::*; - - #[test] - fn test_get() { - assert_eq!(get("translation.test.none"), Some("Hello, world!")); - } -} diff --git a/azalea-nbt/README.md b/azalea-nbt/README.md index 19498cf3..5204c2d4 100755 --- a/azalea-nbt/README.md +++ b/azalea-nbt/README.md @@ -1,3 +1,26 @@ # Azalea NBT A fast NBT serializer and deserializer. + +# Examples + +``` +use ahash::AHashMap; +use azalea_nbt::Tag; +use std::{io::{Cursor, Read}, fs::File}; + +let mut file = File::open("tests/hello_world.nbt").unwrap(); +let mut buf = vec![]; +file.read_to_end(&mut buf).unwrap(); +let tag = Tag::read(&mut Cursor::new(&buf[..])).unwrap(); +assert_eq!( + tag, + Tag::Compound(AHashMap::from_iter(vec![( + "hello world".to_string(), + Tag::Compound(AHashMap::from_iter(vec![( + "name".to_string(), + Tag::String("Bananrama".to_string()), + )])) + )])) +); +``` diff --git a/azalea-nbt/src/decode.rs b/azalea-nbt/src/decode.rs index ae7cfde6..1ec7a912 100755 --- a/azalea-nbt/src/decode.rs +++ b/azalea-nbt/src/decode.rs @@ -35,6 +35,8 @@ fn read_string(stream: &mut Cursor<&[u8]>) -> Result { } impl Tag { + /// Read the NBT data when you already know the ID of the tag. You usually + /// want [`Tag::read`] if you're reading an NBT file. #[inline] fn read_known(stream: &mut Cursor<&[u8]>, id: u8) -> Result { Ok(match id { @@ -129,6 +131,7 @@ impl Tag { }) } + /// Read the NBT data. This will return a compound tag with a single item. pub fn read(stream: &mut Cursor<&[u8]>) -> Result { // default to compound tag @@ -145,6 +148,7 @@ impl Tag { Ok(Tag::Compound(map)) } + /// Read the NBT data compressed wtih zlib. pub fn read_zlib(stream: &mut impl BufRead) -> Result { let mut gz = ZlibDecoder::new(stream); let mut buf = Vec::new(); @@ -152,6 +156,7 @@ impl Tag { Tag::read(&mut Cursor::new(&buf)) } + /// Read the NBT data compressed wtih gzip. pub fn read_gzip(stream: &mut Cursor>) -> Result { let mut gz = GzDecoder::new(stream); let mut buf = Vec::new(); diff --git a/azalea-nbt/src/encode.rs b/azalea-nbt/src/encode.rs index 87464fd9..a4df15c1 100755 --- a/azalea-nbt/src/encode.rs +++ b/azalea-nbt/src/encode.rs @@ -6,8 +6,6 @@ use byteorder::{WriteBytesExt, BE}; use flate2::write::{GzEncoder, ZlibEncoder}; use std::io::Write; -// who needs friends when you've got code that runs in nanoseconds? - #[inline] fn write_string(writer: &mut dyn Write, string: &str) -> Result<(), Error> { writer.write_u16::(string.len() as u16)?; @@ -166,6 +164,10 @@ fn write_longarray(writer: &mut dyn Write, value: &Vec) -> Result<(), Error } impl Tag { + /// Write the tag as unnamed, uncompressed NBT data. If you're writing a + /// compound tag and the length of the NBT is already known, use + /// [`Tag::write`] to avoid the `End` tag (this is used when writing NBT to + /// a file). #[inline] pub fn write_without_end(&self, writer: &mut dyn Write) -> Result<(), Error> { match self { @@ -187,6 +189,11 @@ impl Tag { Ok(()) } + /// Write the compound tag as NBT data. + /// + /// # Errors + /// + /// Returns an `Err` if it's not a Compound or End tag. pub fn write(&self, writer: &mut impl Write) -> Result<(), Error> { match self { Tag::Compound(value) => { @@ -201,11 +208,21 @@ impl Tag { } } + /// Write the compound tag as NBT data compressed wtih zlib. + /// + /// # Errors + /// + /// Returns an `Err` if it's not a Compound or End tag. pub fn write_zlib(&self, writer: &mut impl Write) -> Result<(), Error> { let mut encoder = ZlibEncoder::new(writer, flate2::Compression::default()); self.write(&mut encoder) } + /// Write the compound tag as NBT data compressed wtih gzip. + /// + /// # Errors + /// + /// Returns an `Err` if it's not a Compound or End tag. pub fn write_gzip(&self, writer: &mut impl Write) -> Result<(), Error> { let mut encoder = GzEncoder::new(writer, flate2::Compression::default()); self.write(&mut encoder) diff --git a/azalea-nbt/src/lib.rs b/azalea-nbt/src/lib.rs index e20049e0..4d096776 100755 --- a/azalea-nbt/src/lib.rs +++ b/azalea-nbt/src/lib.rs @@ -1,3 +1,5 @@ +#![doc = include_str!("../README.md")] + mod decode; mod encode; mod error; diff --git a/azalea-nbt/src/tag.rs b/azalea-nbt/src/tag.rs index 2bebe156..65b152fa 100755 --- a/azalea-nbt/src/tag.rs +++ b/azalea-nbt/src/tag.rs @@ -1,6 +1,7 @@ use ahash::AHashMap; use serde::{Deserialize, Serialize}; +/// An NBT value. #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] #[serde(untagged)] pub enum Tag { @@ -26,6 +27,7 @@ impl Default for Tag { } impl Tag { + /// Get the numerical ID of the tag type. #[inline] pub fn id(&self) -> u8 { match self { @@ -45,6 +47,7 @@ impl Tag { } } + /// If the type is a byte, return the [`i8`]. #[inline] pub fn as_byte(&self) -> Option<&i8> { if let Tag::Byte(v) = self { @@ -54,6 +57,7 @@ impl Tag { } } + /// If the type is a short, return the [`i16`]. #[inline] pub fn as_short(&self) -> Option<&i16> { if let Tag::Short(v) = self { @@ -63,6 +67,7 @@ impl Tag { } } + /// If the type is an int, return the [`i32`]. #[inline] pub fn as_int(&self) -> Option<&i32> { if let Tag::Int(v) = self { @@ -72,6 +77,7 @@ impl Tag { } } + /// If the type is a long, return the [`i64`]. #[inline] pub fn as_long(&self) -> Option<&i64> { if let Tag::Long(v) = self { @@ -81,6 +87,7 @@ impl Tag { } } + /// If the type is a float, return the [`f32`]. #[inline] pub fn as_float(&self) -> Option<&f32> { if let Tag::Float(v) = self { @@ -90,6 +97,7 @@ impl Tag { } } + /// If the type is a double, return the [`f64`]. #[inline] pub fn as_double(&self) -> Option<&f64> { if let Tag::Double(v) = self { @@ -99,6 +107,7 @@ impl Tag { } } + /// If the type is a string, return the [`str`]. #[inline] pub fn as_string(&self) -> Option<&str> { if let Tag::String(v) = self { @@ -108,6 +117,7 @@ impl Tag { } } + /// If the type is a compound, return the `AHashMap`. #[inline] pub fn as_compound(&self) -> Option<&AHashMap> { if let Tag::Compound(v) = self { @@ -117,6 +127,7 @@ impl Tag { } } + /// If the type is a bytearray, return the `[u8]`. #[inline] pub fn as_bytearray(&self) -> Option<&[u8]> { if let Tag::ByteArray(v) = self { @@ -126,6 +137,7 @@ impl Tag { } } + /// If the type is an intarray, return the `Vec`. #[inline] pub fn as_intarray(&self) -> Option<&Vec> { if let Tag::IntArray(v) = self { @@ -135,6 +147,7 @@ impl Tag { } } + /// If the type is a longarray, return the `Vec`. #[inline] pub fn as_longarray(&self) -> Option<&Vec> { if let Tag::LongArray(v) = self { @@ -144,6 +157,7 @@ impl Tag { } } + /// If the type is a list, return the `[Tag]`. #[inline] pub fn as_list(&self) -> Option<&[Tag]> { if let Tag::List(v) = self { diff --git a/azalea-physics/src/lib.rs b/azalea-physics/src/lib.rs index 76ae3990..2409dff7 100644 --- a/azalea-physics/src/lib.rs +++ b/azalea-physics/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README.md")] #![feature(trait_alias)] pub mod collision; diff --git a/azalea-registry/src/lib.rs b/azalea-registry/src/lib.rs index e9a5f550..7a0b9234 100755 --- a/azalea-registry/src/lib.rs +++ b/azalea-registry/src/lib.rs @@ -1,3 +1,5 @@ +#![doc = include_str!("../README.md")] + // This file is automatically generated in codegen/lib/code/registry.py use azalea_buf::{BufReadError, McBufReadable, McBufVarReadable, McBufVarWritable, McBufWritable}; diff --git a/azalea-world/src/lib.rs b/azalea-world/src/lib.rs index 05cc7d85..5ea5db17 100644 --- a/azalea-world/src/lib.rs +++ b/azalea-world/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README.md")] #![feature(int_roundings)] #![feature(error_generic_member_access)] #![feature(provide_any)] diff --git a/codegen/lib/code/registry.py b/codegen/lib/code/registry.py index 4df82c09..86f5f02d 100755 --- a/codegen/lib/code/registry.py +++ b/codegen/lib/code/registry.py @@ -9,7 +9,9 @@ REGISTRIES_DIR = get_dir_location('../azalea-registry/src/lib.rs') def generate_registries(registries: dict): code = [] - code.append('''// This file is automatically generated in codegen/lib/code/registry.py + code.append('''#![doc = include_str!("../README.md")] + +// This file is automatically generated in codegen/lib/code/registry.py use azalea_buf::{BufReadError, McBufReadable, McBufVarReadable, McBufVarWritable, McBufWritable}; use azalea_registry_macros::registry;