have docs for all crates

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).

azalea-auth/src/lib.rs

@@ -1,3 +1,5 @@
+#![doc = include_str!("../README.md")]
+
 mod auth;
 mod cache;
 pub mod game_profile;

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;

azalea-block/src/lib.rs

@@ -1,3 +1,5 @@
+#![doc = include_str!("../README.md")]
+
 mod behavior;
 mod blocks;
 

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).

azalea-brigadier/src/lib.rs

@@ -1,3 +1,5 @@
+#![doc = include_str!("../README.md")]
+
 pub mod arguments;
 pub mod builder;
 pub mod command_dispatcher;

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)]

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"
+);
+```

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;

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.

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)]

azalea-crypto/src/lib.rs

@@ -1,3 +1,5 @@
+#![doc = include_str!("../README.md")]
+
 mod signing;
 
 use aes::cipher::inout::InOutBuf;

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!"));
+```

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<HashMap<String, String>> =
 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!"));
-    }
-}

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()),
+        )]))
+    )]))
+);
+```

azalea-nbt/src/decode.rs

@@ -35,6 +35,8 @@ fn read_string(stream: &mut Cursor<&[u8]>) -> Result<String, Error> {
 }
 
 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<Tag, Error> {
         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<Tag, Error> {
         // 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<Tag, Error> {
         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<Vec<u8>>) -> Result<Tag, Error> {
         let mut gz = GzDecoder::new(stream);
         let mut buf = Vec::new();

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::<BE>(string.len() as u16)?;
@@ -166,6 +164,10 @@ fn write_longarray(writer: &mut dyn Write, value: &Vec<i64>) -> 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)

azalea-nbt/src/lib.rs

@@ -1,3 +1,5 @@
+#![doc = include_str!("../README.md")]
+
 mod decode;
 mod encode;
 mod error;

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<String, Tag>`.
     #[inline]
     pub fn as_compound(&self) -> Option<&AHashMap<String, Tag>> {
         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<i32>`.
     #[inline]
     pub fn as_intarray(&self) -> Option<&Vec<i32>> {
         if let Tag::IntArray(v) = self {
@@ -135,6 +147,7 @@ impl Tag {
         }
     }
 
+    /// If the type is a longarray, return the `Vec<i64>`.
     #[inline]
     pub fn as_longarray(&self) -> Option<&Vec<i64>> {
         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 {

azalea-physics/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 #![feature(trait_alias)]
 
 pub mod collision;

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};

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)]

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;