polish readmes

18 files changed, 58 insertions, 56 deletions

diff --git a/README.md b/README.md
index 142cdd95..2ca162f8 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@ _Currently supported Minecraft version: `1.21.11`._
 
 ## Features
 
-- [Accurate physics](https://github.com/azalea-rs/azalea/blob/main/azalea-physics/src/lib.rs) (but some features like entity pushing and elytras aren't implemented yet)
+- [Accurate physics](https://azalea.matdoes.dev/azalea_physics/) (but some features like entity pushing and elytras aren't implemented yet)
 - [Pathfinder](https://azalea.matdoes.dev/azalea/pathfinder/index.html)
 - [Swarms](https://azalea.matdoes.dev/azalea/swarm/index.html)
 - [Breaking blocks](https://azalea.matdoes.dev/azalea/struct.Client.html#method.mine)
@@ -26,29 +26,29 @@ _Currently supported Minecraft version: `1.21.11`._
 - [Attacking entities](https://azalea.matdoes.dev/azalea/struct.Client.html#method.attack)
 - [Plugins](#plugins)
 
-## Docs
-
-The "stable" documentation is available at [docs.rs/azalea](https://docs.rs/azalea) and the unstable docs are at [azalea.matdoes.dev](https://azalea.matdoes.dev) (recommended).
-
-## Matrix/Discord
-
-If you'd like to chat about Azalea, you can join the Matrix space at [#azalea:matdoes.dev](https://matrix.to/#/#azalea:matdoes.dev) (recommended) or the Discord server at [discord.gg/FaRey6ytmC](https://discord.gg/FaRey6ytmC) (they're bridged so you don't need to join both).
-
 ## Goals
 
-- Do everything a vanilla client can do.
-- Be intuitive and easy to use.
+- Support everything that a vanilla Minecraft client can do.
+- Have an intuitive and easy to use API.
 - Make it easy to have many bots working at the same time.
-- Don't trigger anticheats.
+- Don't trigger anti-cheats.
 - Support the latest Minecraft version.
-- Be fast and memory efficient.
+- Be fast and efficient.
 
 ## Non-goals
 
-- Supporting several versions of Minecraft on the same branch[\*](https://github.com/azalea-rs/azalea-viaversion).
+- Supporting multiple versions of Minecraft at the same time[\*](https://github.com/azalea-rs/azalea-viaversion).
 - Graphics[\*](https://github.com/urisinger/azalea-graphics).
 - Bedrock edition.
 
+## Documentation
+
+The stable documentation for the main `azalea` crate is available at [docs.rs/azalea](https://docs.rs/azalea), and the unstable documentation is at [azalea.matdoes.dev](https://azalea.matdoes.dev).
+
+## Matrix/Discord
+
+If you'd like to chat about Azalea, you can join the Matrix space at [#azalea:matdoes.dev](https://matrix.to/#/#azalea:matdoes.dev) or the Discord server at [discord.gg/FaRey6ytmC](https://discord.gg/FaRey6ytmC). The channels are bridged so you don't need to join both.
+
 ## Real-world bots using Azalea
 
 Here's an incomplete list of bots built using Azalea, primarily intended as a reference in addition to the existing documentation and examples:
@@ -63,7 +63,8 @@ You can see more projects built with Azalea in the [GitHub dependency graph](htt
 
 ## Plugins
 
-Azalea has support for Bevy plugins, which can significantly alter its functionality. Here are some plugins that you may find useful:
+Azalea has support for Bevy plugins which can significantly alter its functionality.
+Here are some plugins that you may find useful:
 
 - [azalea-rs/azalea-viaversion](https://github.com/azalea-rs/azalea-viaversion) - Multi-version compatibility for your Azalea bots using ViaProxy.
 - [azalea-rs/azalea-hax](https://github.com/azalea-rs/azalea-hax) - Anti-knockback.
@@ -72,12 +73,5 @@ If you've created your own plugin for Azalea, please create a PR to add it to th
 
 ## Funding
 
-Azalea is currently maintained primarily by one person (mat) as a hobby project. If you appreciate Azalea, consider [donating on Ko-fi](https://ko-fi.com/matdoesdev).
-
-## FAQ
-
-- There's too many console messages, how do I disable them?
-
-  You can disable all console messages by setting the `RUST_LOG` environment variable to `off`, or you can filter log messages by setting specific log levels. For example, to disable only pathfinding logs, you can set `RUST_LOG=azalea::pathfinder=off`.
+Azalea is currently maintained primarily by one person as a hobby project. If you appreciate Azalea, consider [donating on Ko-fi](https://ko-fi.com/matdoesdev).
 
-  See the [`env_logger`](https://docs.rs/env_logger/latest/env_logger/) crate documentation for more information.
diff --git a/azalea-auth/README.md b/azalea-auth/README.md
index d7026254..055498c3 100644
--- a/azalea-auth/README.md
+++ b/azalea-auth/README.md
@@ -1,4 +1,4 @@
-# Azalea Auth
+# `azalea-auth`
 
 A port of Mojang's Authlib and launcher authentication.
 
diff --git a/azalea-block/README.md b/azalea-block/README.md
index 81e6b097..ff3e8c31 100644
--- a/azalea-block/README.md
+++ b/azalea-block/README.md
@@ -1,6 +1,8 @@
+# `azalea-block`
+
 Representation of Minecraft block states.
 
-There's three block types, used for different things. You can (mostly) convert between them with `.into()`.
+There are three block types, used for different things. You can (mostly) convert between them with `.into()`.
 
 ## `BlockState` struct
 
@@ -43,7 +45,7 @@ if let Some(jukebox) = Box::<dyn BlockTrait>::from(block_state).downcast_ref::<a
 ```
 
 
-## `azalea_registry::builtin::BlockKind` enum
+## `azalea_registry::builtin::BlockKind`
 
 This one isn't from the `azalea-block` crate, but it's still very relevant. It's an enum that contains every block type as a variant *without* containing any state data (unlike `BlockState` and `BlockTrait`). Converting this into any other block type will use the default state for that block.
 
diff --git a/azalea-brigadier/README.md b/azalea-brigadier/README.md
index 44a5e2c5..f18d253f 100644
--- a/azalea-brigadier/README.md
+++ b/azalea-brigadier/README.md
@@ -1,4 +1,4 @@
-# Azalea Brigadier
+# `azalea-brigadier`
 
 A Rust port of Mojang's [Brigadier](https://github.com/Mojang/brigadier) command parsing and dispatching library.
 
diff --git a/azalea-buf/README.md b/azalea-buf/README.md
index 378f3e05..371f0772 100644
--- a/azalea-buf/README.md
+++ b/azalea-buf/README.md
@@ -1,5 +1,5 @@
-# Azalea Buf
+# `azalea-buf`
 
-An implementation of Minecraft's FriendlyByteBuf. This is used frequently in the game for serialization and deserialization of data.
+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.
diff --git a/azalea-client/README.md b/azalea-client/README.md
index a40f8585..6ec41a0c 100644
--- a/azalea-client/README.md
+++ b/azalea-client/README.md
@@ -1,5 +1,5 @@
-# Azalea Client
+# `azalea-client`
 
-A library that can mimic everything a normal Minecraft client can do.
+A library that can mimic everything that a normal Minecraft client can do.
 
 If you want to make a bot with higher-level functions, consider using the `azalea` crate instead.
diff --git a/azalea-core/README.md b/azalea-core/README.md
index f8564484..efc7cd17 100644
--- a/azalea-core/README.md
+++ b/azalea-core/README.md
@@ -1,3 +1,3 @@
-# Azalea Core
+# `azalea-core`
 
 Random miscellaneous things like `bitsets` and `Vec3` that don't deserve their own crate.
diff --git a/azalea-crypto/README.md b/azalea-crypto/README.md
index 49ec3f2f..6de4fe23 100644
--- a/azalea-crypto/README.md
+++ b/azalea-crypto/README.md
@@ -1,3 +1,3 @@
-# Azalea Crypto
+# `azalea-crypto`
 
 Cryptography features used in Minecraft.
diff --git a/azalea-entity/README.md b/azalea-entity/README.md
new file mode 100644
index 00000000..f8255107
--- /dev/null
+++ b/azalea-entity/README.md
@@ -0,0 +1,3 @@
+# `azalea-entity`
+
+Features related to Minecraft entities used by Azalea.
diff --git a/azalea-entity/src/lib.rs b/azalea-entity/src/lib.rs
index d95a2f20..5bf538aa 100644
--- a/azalea-entity/src/lib.rs
+++ b/azalea-entity/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 #![allow(clippy::derived_hash_with_manual_eq)]
 
 pub mod attributes;
diff --git a/azalea-inventory/README.md b/azalea-inventory/README.md
new file mode 100644
index 00000000..8738c7e9
--- /dev/null
+++ b/azalea-inventory/README.md
@@ -0,0 +1,3 @@
+# `azalea-inventory`
+
+Representations of various inventory data structures from Minecraft.
diff --git a/azalea-inventory/src/lib.rs b/azalea-inventory/src/lib.rs
index 87cd61e4..e95d9ee1 100644
--- a/azalea-inventory/src/lib.rs
+++ b/azalea-inventory/src/lib.rs
@@ -1,5 +1,4 @@
-//! Representations of various inventory data structures in Minecraft.
-
+#![doc = include_str!("../README.md")]
 #![feature(min_specialization)]
 
 pub mod components;
diff --git a/azalea-language/README.md b/azalea-language/README.md
index d2e2b0f4..c105652e 100644
--- a/azalea-language/README.md
+++ b/azalea-language/README.md
@@ -1,6 +1,6 @@
-# Azalea Language
+# `azalea-language`
 
-Translate Minecraft strings from their ID.
+Translate Minecraft strings from their IDs.
 
 # Examples
 
diff --git a/azalea-physics/README.md b/azalea-physics/README.md
index 21ee18ba..04617ad3 100644
--- a/azalea-physics/README.md
+++ b/azalea-physics/README.md
@@ -1,3 +1,3 @@
-# Azalea Physics
+# `azalea-physics`
 
-Physics for Minecraft entities.
+Accurate physics for Minecraft entities.
diff --git a/azalea-protocol/README.md b/azalea-protocol/README.md
index 8c41daa1..1cadc3b4 100644
--- a/azalea-protocol/README.md
+++ b/azalea-protocol/README.md
@@ -1,5 +1,7 @@
-# Azalea Protocol
+# `azalea-protocol`
 
-A low-level crate to send and receive Minecraft packets. If you intend on making bots, you should use the main `azalea` crate instead.
+A low-level crate for sending and receiving Minecraft packets.
 
 Only the latest Minecraft version is supported.
+
+See [`crate::connect::Connection`] for usage.
diff --git a/azalea-protocol/src/lib.rs b/azalea-protocol/src/lib.rs
index 803f8630..dfff7da7 100644
--- a/azalea-protocol/src/lib.rs
+++ b/azalea-protocol/src/lib.rs
@@ -1,14 +1,4 @@
-//! A low-level crate to send and receive Minecraft packets.
-//!
-//! You should probably use [`azalea`] or [`azalea_client`] instead, as
-//! `azalea_protocol` delegates much of the work, such as auth, to the user of
-//! the crate.
-//!
-//! [`azalea`]: https://crates.io/crates/azalea
-//! [`azalea_client`]: https://crates.io/crates/azalea-client
-//!
-//! See [`crate::connect::Connection`] for an example.
-
+#![doc = include_str!("../README.md")]
 // this is necessary for thiserror backtraces
 #![feature(error_generic_member_access)]
 
diff --git a/azalea-world/README.md b/azalea-world/README.md
index 9b237db0..79a08f1c 100644
--- a/azalea-world/README.md
+++ b/azalea-world/README.md
@@ -1 +1,3 @@
-The Minecraft world representation used in Azalea.
+# `azalea-world`
+
+The Minecraft world representation used by Azalea.
diff --git a/azalea/README.md b/azalea/README.md
index 6b5c2601..e44036c3 100644
--- a/azalea/README.md
+++ b/azalea/README.md
@@ -1,7 +1,6 @@
 Azalea is a framework for creating Minecraft bots.
 
-This page is primarily meant for developers that already know they want to use Azalea.
-See the [readme](https://github.com/azalea-rs/azalea) for a higher-level overview of Azalea.
+Also see the project [README](https://github.com/azalea-rs/azalea) for a higher-level overview of Azalea.
 
 # Installation
 
@@ -116,10 +115,17 @@ If your code is simply hanging, it might be a deadlock. Enable `parking_lot`'s `
 
 Backtraces are also useful, though they're sometimes hard to read and don't always contain the actual location of the error. Run your code with `RUST_BACKTRACE=1` to enable full backtraces. If it's very long, often searching for the keyword "azalea" will help you filter out unrelated things and find the actual source of the issue.
 
-# Other common problems
+# Other notes
 
 ## Using `tokio::task::spawn_local` instead of `tokio::spawn`
 
 If you spawn a task with `tokio::spawn` and move your bot into it, it's possible for Tokio to run the handler function or schedule a Minecraft tick at an unexpected moment. For instance, `bot.component::<TicksConnected>() == bot.component::<TicksConnected>()` is not guaranteed to be true inside of a `tokio::spawn`. Azalea already mitigates this in the handler function by using a Tokio [LocalSet](https://docs.rs/tokio/latest/tokio/task/struct.LocalSet.html), but that mitigation does not apply if you call `tokio::spawn` yourself. To avoid this, you must call `tokio::task::spawn_local` in place of `tokio::spawn`. Alternatively, you could also mark your main function with `#[tokio::main(flavor = "current_thread")]`.
 
+## Disabling log messages
+
+You can disable all console messages by setting the `RUST_LOG` environment variable to `off`, or you can filter log messages by setting specific log levels. For example, to disable only pathfinding logs, you can set `RUST_LOG=azalea::pathfinder=off`.
+
+See the [`env_logger`](https://docs.rs/env_logger/latest/env_logger/) crate documentation for more information.
+
 [`bevy_log`]: https://docs.rs/bevy_log
+