From 392b93d47baeb6bee26c0eda86ac67748eb8af1b Mon Sep 17 00:00:00 2001
From: demenik <dominik.bernroider@icloud.com>
Date: Wed, 10 Dec 2025 18:13:22 +0100
Subject: [PATCH] docs: add documentation for inventory and shop systems (#65)

---
 src/features/inventory/components.rs   | 7 +++++++
 src/features/inventory/mod.rs          | 3 +++
 src/features/inventory/ui/inventory.rs | 1 +
 src/features/inventory/ui/item.rs      | 1 +
 src/features/shop/components.rs        | 5 +++++
 src/features/shop/mod.rs               | 2 ++
 src/features/shop/ui/offer.rs          | 2 ++
 src/features/shop/ui/shop.rs           | 1 +
 8 files changed, 22 insertions(+)

diff --git a/src/features/inventory/components.rs b/src/features/inventory/components.rs
index ab3f75a..2efa7a6 100644
--- a/src/features/inventory/components.rs
+++ b/src/features/inventory/components.rs
@@ -1,6 +1,7 @@
 use crate::features::config::components::BerrySeedConfig;
 use crate::prelude::*;
 
+/// Types of items available in the game.
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, Hash)]
 pub enum ItemType {
     Berry,
@@ -102,18 +103,21 @@ impl ItemType {
     }
 }
 
+/// A stack of items of a specific type.
 #[derive(Component, Serialize, Deserialize, Clone, Debug)]
 pub struct ItemStack {
     pub item_type: ItemType,
     pub amount: u32,
 }
 
+/// Resource containing all items owned by the player.
 #[derive(Resource, Default, Serialize, Deserialize)]
 pub struct Inventory {
     pub items: Vec<Entity>,
 }
 
 impl Inventory {
+    /// Checks if the inventory contains a specific item type.
     pub fn has_item_type(&self, items_query: &Query<&ItemStack>, item_type: ItemType) -> bool {
         self.items.iter().any(|&entity| {
             if let Ok(stack) = items_query.get(entity) {
@@ -124,6 +128,7 @@ impl Inventory {
         })
     }
 
+    /// Adds or removes items from the inventory.
     pub fn update_item_stack(
         &mut self,
         commands: &mut Commands,
@@ -193,11 +198,13 @@ impl Inventory {
     }
 }
 
+/// Markers for inventory UI root nodes.
 #[derive(Component)]
 pub enum RootMarker {
     Inventory,
 }
 
+/// Markers for inventory-related buttons.
 #[derive(Component)]
 pub enum ButtonType {
     InventoryOpen,
diff --git a/src/features/inventory/mod.rs b/src/features/inventory/mod.rs
index 49df63b..878fc95 100644
--- a/src/features/inventory/mod.rs
+++ b/src/features/inventory/mod.rs
@@ -5,6 +5,7 @@ use components::*;
 pub mod components;
 pub mod ui;
 
+/// Plugin for the inventory system, including storage and UI.
 pub struct InventoryPlugin;
 
 impl Plugin for InventoryPlugin {
@@ -18,6 +19,7 @@ impl Plugin for InventoryPlugin {
     }
 }
 
+/// Handles inventory button interactions.
 fn buttons(
     mut commands: Commands,
     mut interaction_query: Query<(&Interaction, &ButtonType), (Changed<Interaction>, With<Button>)>,
@@ -37,6 +39,7 @@ fn buttons(
     }
 }
 
+/// Debug system to add/remove berries with arrow keys.
 #[cfg(debug_assertions)]
 fn debug_modify_berries(
     mut commands: Commands,
diff --git a/src/features/inventory/ui/inventory.rs b/src/features/inventory/ui/inventory.rs
index d98ce79..a807c48 100644
--- a/src/features/inventory/ui/inventory.rs
+++ b/src/features/inventory/ui/inventory.rs
@@ -2,6 +2,7 @@ use super::super::components::RootMarker;
 use crate::prelude::GameConfig;
 use crate::{features::inventory::ui::list_itemstack, prelude::*};
 
+/// Spawns the inventory popup.
 pub fn open_inventory(
     commands: &mut Commands,
     items: Query<&ItemStack>,
diff --git a/src/features/inventory/ui/item.rs b/src/features/inventory/ui/item.rs
index 39a9f0a..9088e93 100644
--- a/src/features/inventory/ui/item.rs
+++ b/src/features/inventory/ui/item.rs
@@ -1,5 +1,6 @@
 use crate::prelude::*;
 
+/// Creates a UI bundle for a single item stack in the inventory list.
 pub fn list_itemstack(
     itemstack: &ItemStack,
     game_config: &GameConfig,
diff --git a/src/features/shop/components.rs b/src/features/shop/components.rs
index d479bbd..99288d4 100644
--- a/src/features/shop/components.rs
+++ b/src/features/shop/components.rs
@@ -1,16 +1,19 @@
 use crate::prelude::*;
 
+/// Markers for shop UI.
 #[derive(Component)]
 pub enum RootMarker {
     Shop,
 }
 
+/// Buttons in the shop.
 #[derive(Component)]
 pub enum ButtonType {
     ShopOpen,
     ShopBuyItem(ShopOffer),
 }
 
+/// An item available for purchase.
 #[derive(Clone)]
 pub struct ShopOffer {
     pub item: ItemStack,
@@ -18,6 +21,7 @@ pub struct ShopOffer {
 }
 
 impl ShopOffer {
+    /// Generates a list of all current offers.
     pub fn list_all(game_config: &GameConfig, tile_count: u32) -> Vec<ShopOffer> {
         let mut offers = Vec::new();
 
@@ -50,6 +54,7 @@ impl ShopOffer {
         offers
     }
 
+    /// Attempts to purchase the offer.
     pub fn buy(
         &self,
         inventory: &mut Inventory,
diff --git a/src/features/shop/mod.rs b/src/features/shop/mod.rs
index b347b56..a8a65ac 100644
--- a/src/features/shop/mod.rs
+++ b/src/features/shop/mod.rs
@@ -5,6 +5,7 @@ use ui::open_shop;
 pub mod components;
 pub mod ui;
 
+/// Plugin for the in-game shop.
 pub struct ShopPlugin;
 
 impl Plugin for ShopPlugin {
@@ -13,6 +14,7 @@ impl Plugin for ShopPlugin {
     }
 }
 
+/// Handles shop button interactions.
 fn buttons(
     mut commands: Commands,
     mut interaction_query: Query<(&Interaction, &ButtonType), (Changed<Interaction>, With<Button>)>,
diff --git a/src/features/shop/ui/offer.rs b/src/features/shop/ui/offer.rs
index 6c971b7..c15af2b 100644
--- a/src/features/shop/ui/offer.rs
+++ b/src/features/shop/ui/offer.rs
@@ -1,6 +1,7 @@
 use super::super::components::*;
 use crate::{features::inventory::ui::item::list_itemstack, prelude::*};
 
+/// Creates the UI bundle for a shop offer.
 pub fn shop_offer(
     offer: &ShopOffer,
     game_config: &GameConfig,
@@ -26,6 +27,7 @@ pub fn shop_offer(
     )
 }
 
+/// Creates the UI bundle for displaying a price.
 pub fn shop_price(
     price: u32,
     asset_server: &Res<AssetServer>,
diff --git a/src/features/shop/ui/shop.rs b/src/features/shop/ui/shop.rs
index 4983b00..2ef28c8 100644
--- a/src/features/shop/ui/shop.rs
+++ b/src/features/shop/ui/shop.rs
@@ -1,6 +1,7 @@
 use super::super::components::*;
 use crate::{features::shop::ui::shop_offer, prelude::*};
 
+/// Spawns the shop popup.
 pub fn open_shop(
     commands: &mut Commands,
     game_config: &GameConfig,