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

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.
+#![doc = include_str!("../README.md")]
-//! This was inspired by Minecraft and prismarine-chat.
 
 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;