From 6c84fe0ac09d408bff3ca2d1aefe63134378af6d Mon Sep 17 00:00:00 2001
From: Luis Michaelis <me@lmichaelis.de>
Date: Thu, 28 Dec 2023 15:39:10 +0100
Subject: [PATCH] docs(VItem): add documentation for `oCItem`

---
 docs/engine/objects/oCItem.md | 30 ++++++++++++++++++++++++++++++
 include/zenkit/vobs/Misc.hh   | 23 ++++++++++++++++-------
 mkdocs.yml                    |  1 +
 3 files changed, 47 insertions(+), 7 deletions(-)
 create mode 100644 docs/engine/objects/oCItem.md

diff --git a/docs/engine/objects/oCItem.md b/docs/engine/objects/oCItem.md
new file mode 100644
index 00000000..90dd3616
--- /dev/null
+++ b/docs/engine/objects/oCItem.md
@@ -0,0 +1,30 @@
+# oCItem
+
+!!! abstract inline end "Quick Infos"
+    **Type:** Virtual Object<br/>
+    **Format Name:** ZenGin Archive<br/>
+    **File Extension:** `.ZEN`<br/>
+    **Class Name:** `oCItem`<br/>
+    **Version Identifiers:**<br />
+    — Gothic I: `0`<br/>
+    — Gothic II: `0`<br/>
+    **ZenKit Class:** `VItem`
+
+Represents an item in the game world. Items are special VObjects which are tied to a script instance which defines
+their attributes. They have physics enabled and can be targeted and picked up by the player.
+
+<ul class="sp-list">
+    <li class="sp-type"><a href="../zCVob/">zCVob</a></li>
+    <li class="sp-type">
+        <span>oCItem</span>
+        <ul class="sp-list">
+            <li class="sp-string"><a href="#itemInstance">itemInstance</a> = ""</li>
+        </ul>
+    </li>
+</ul>
+
+## Properties
+
+<a name="itemInstance" class="t-str"></a> `itemInstance`
+
+:   The name of the script instance representing the item.
diff --git a/include/zenkit/vobs/Misc.hh b/include/zenkit/vobs/Misc.hh
index aff2da9f..f7c26372 100644
--- a/include/zenkit/vobs/Misc.hh
+++ b/include/zenkit/vobs/Misc.hh
@@ -86,27 +86,36 @@ namespace zenkit {
 		ZKAPI void save(WriteArchive& w, GameVersion version) const override;
 	};
 
-	/// \brief A VOb representing an in-game item.
+	/// \brief Represents an item in the game world.
+	///
+	/// Items are special VObjects which are tied to a script instance which defines their attributes. They
+	/// have physics enabled and can be targeted and picked up by the player.
+	///
+	/// \see https://zk.gothickit.dev/engine/objects/oCItem/
 	struct VItem : VirtualObject {
 		ZK_OBJECT(ObjectType::oCItem);
 
 	public:
+		/// \brief The name of the script instance representing the item.
+		/// \see https://zk.gothickit.dev/engine/objects/oCItem/#itemInstance
 		std::string instance;
 
 		// Save-game only variables
 		int s_amount;
 		int s_flags;
 
-		/// \brief Parses an item VOb the given *ZenGin* archive.
-		/// \param[out] obj The object to read.
-		/// \param[in,out] ctx The archive reader to read from.
-		/// \note After this function returns the position of \p ctx will be at the end of the parsed object.
-		/// \throws ParserError if parsing fails.
-		/// \see vob::parse
 		ZKREM("use ::load()") ZKAPI static void parse(VItem& obj, ReadArchive& ctx, GameVersion version);
 
+		/// \brief Load this object from the given archive.
+		/// \param r The archive to read from;
+		/// \param version The version of the game the object was made for.
 		ZKAPI void load(ReadArchive& r, GameVersion version) override;
+
+		/// \brief Save this object to the given archive.
+		/// \param w The archive to save to.
+		/// \param version The version of the game to save for.
 		ZKAPI void save(WriteArchive& w, GameVersion version) const override;
+
 		[[nodiscard]] ZKAPI uint16_t get_version_identifier(GameVersion game) const override;
 	};
 
diff --git a/mkdocs.yml b/mkdocs.yml
index 661e1bb4..41b8db89 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -44,6 +44,7 @@ nav:
           - 'zCVobSpot': 'engine/objects/zCVobSpot.md'
           - 'zCVobStair': 'engine/objects/zCVobStair.md'
           - 'zCVobStartpoint': 'engine/objects/zCVobStartpoint.md'
+          - 'oCItem': 'engine/objects/oCItem.md'
           - 'zCVisual': 'engine/objects/zCVisual.md'
           - 'zCDecal': 'engine/objects/zCDecal.md'
       - 'Encodings':