make blockstate good

1 files changed, 44 insertions, 7 deletions

diff --git a/azalea-block/README.md b/azalea-block/README.md
index efeda675..a2a72352 100755
--- a/azalea-block/README.md
+++ b/azalea-block/README.md
@@ -1,12 +1,49 @@
-# Azalea Block
-
 Representation of Minecraft block states.
 
-There's two main things here, the `BlockState` enum and the `Block` trait.
-`BlockState` is a simple enum with every possible block state as variant, and `Block` is a heavier trait which lets you access information about a block more easily.
+There's three block types, used for different things. You can (mostly) freely convert between them with `.into()`.
+
+## BlockState struct
+
+[`BlockState`] is a struct containing the numerical protocol ID of a block state. This is how blocks are stored in the world.
+
+
+```
+# use azalea_block::BlockState;
+let block_state: BlockState = azalea_registry::Block::Jukebox.into();
+```
+
+## Block trait
+
+The [`Block`] trait represents a type of a block. With the the [`Block`] trait, you can get some extra things like the string block ID and some information about the block's behavior. Also, the structs that implement the trait contain the block attributes as fields so it's more convenient to get them. Note that this is often used as `Box<dyn Block>`.
+If for some reason you don't want the `Block` trait, set default-features to false.
+
+```
+# use azalea_block::{Block, BlockState};
+# let block_state: BlockState = azalea_registry::Block::Jukebox.into();
+if let Some(jukebox) = Box::<dyn Block>::from(block_state).downcast_ref::<azalea_block::JukeboxBlock>() {
+    // ...
+}
+```
+```
+# use azalea_block::BlockState;
+let block_state: BlockState = azalea_block::CobblestoneWallBlock {
+    east: azalea_block::EastWall::Low,
+    north: azalea_block::NorthWall::Low,
+    south: azalea_block::SouthWall::Low,
+    west: azalea_block::WestWall::Low,
+    up: false,
+    waterlogged: false,
+}
+.into();
+```
+
+
+## azalea_registry::Block enum
 
-Every block is a struct that implements `Block`. You can freely convert between `BlockState` and `Block` with .into().
+This one technically 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 (like `BlockState` and the `Block` trait). Converting this into any other block type will use the default state for that block.
 
-If you don't want the `Block` trait, set default-features to false.
+```
+# use azalea_block::BlockState;
+let block_state: BlockState = azalea_registry::Block::Jukebox.into();
+```
 
-Also, by default the `Debug` implementation for `BlockState` only logs the name of the block and not the name of the enum variant. If you want that, enable the `full-debug` feature (though it's not recommended).