add docs

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;

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

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";