From 810519fb4d0cfbd7303c8518908deaaeb57a7ccd Mon Sep 17 00:00:00 2001
From: MihailRis <mexaruc@gmail.com>
Date: Sun, 18 Aug 2024 17:29:02 +0300
Subject: [PATCH] add docs

---
 src/world/generator/GeneratorDef.hpp   | 19 +++++++++++++++++++
 src/world/generator/WorldGenerator.cpp |  4 ++--
 src/world/generator/WorldGenerator.hpp |  6 ++++++
 3 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/src/world/generator/GeneratorDef.hpp b/src/world/generator/GeneratorDef.hpp
index 7852637c..649d3548 100644
--- a/src/world/generator/GeneratorDef.hpp
+++ b/src/world/generator/GeneratorDef.hpp
@@ -9,24 +9,40 @@
 class Content;
 
 struct BlocksLayer {
+    /// @brief Layer block
     std::string block;
+    
+    /// @brief Layer height. -1 is resizeable layer
     int height;
+
+    /// @brief Layer can present under the sea level (default: true) else will
+    /// extend the next layer
     bool below_sea_level;
 
     struct {
+        /// @brief Layer block index
         blockid_t id;
     } rt;
 };
 
+/// @brief Set of blocks layers with additional info
 struct BlocksLayers {
     std::vector<BlocksLayer> layers;
+
+    /// @brief Total height of all layers after the resizeable one
     uint lastLayersHeight;
 };
 
+/// @brief Generator behaviour and settings interface
 class GeneratorScript {
 public:
     virtual ~GeneratorScript() = default;
 
+    /// @brief Generates a heightmap with values in range 0..1
+    /// @param offset position of the heightmap top left corner in the world
+    /// @param size size of the heightmap
+    /// @param seed world seed
+    /// @return generated heightmap of given size (can't be nullptr)
     virtual std::shared_ptr<Heightmap> generateHeightmap(
         const glm::ivec2& offset, const glm::ivec2& size, uint64_t seed) = 0;
 
@@ -35,9 +51,12 @@ public:
 
     virtual uint getSeaLevel() const = 0;
 
+    /// @brief Build the runtime cache
+    /// @param content built content
     virtual void prepare(const Content* content) = 0;
 };
 
+/// @brief Generator information
 struct GeneratorDef {
     std::string name;
     std::unique_ptr<GeneratorScript> script;
diff --git a/src/world/generator/WorldGenerator.cpp b/src/world/generator/WorldGenerator.cpp
index 0f0dea6e..a8cd1763 100644
--- a/src/world/generator/WorldGenerator.cpp
+++ b/src/world/generator/WorldGenerator.cpp
@@ -15,14 +15,14 @@ WorldGenerator::WorldGenerator(const GeneratorDef& def, const Content* content)
 
 static inline void generate_pole(
     const BlocksLayers& layers,
-    int height,
+    int top,
     int bottom,
     int seaLevel,
     voxel* voxels,
     int x,
     int z
 ) {
-    uint y = height;
+    uint y = top;
     uint layerExtension = 0;
     for (const auto& layer : layers.layers) {
         // skip layer if can't be generated under sea level
diff --git a/src/world/generator/WorldGenerator.hpp b/src/world/generator/WorldGenerator.hpp
index 67be501e..93127d10 100644
--- a/src/world/generator/WorldGenerator.hpp
+++ b/src/world/generator/WorldGenerator.hpp
@@ -8,6 +8,7 @@ struct voxel;
 class Content;
 struct GeneratorDef;
 
+/// @brief High-level world generation controller
 class WorldGenerator {
     const GeneratorDef& def;
     const Content* content;
@@ -18,6 +19,11 @@ public:
     );
     virtual ~WorldGenerator() = default;
 
+    /// @brief Generate complete chunk voxels
+    /// @param voxels destinatiopn chunk voxels buffer
+    /// @param x chunk position X divided by CHUNK_W
+    /// @param z chunk position Y divided by CHUNK_D
+    /// @param seed world seed
     virtual void generate(voxel* voxels, int x, int z, uint64_t seed);
 
     inline static std::string DEFAULT = "core:default";