From 6ed0bc3e7e401ca0318e383c8bec1f9a05eb88e6 Mon Sep 17 00:00:00 2001
From: MihailRis <mexaruc@gmail.com>
Date: Mon, 16 Dec 2024 23:56:52 +0300
Subject: [PATCH] add docs to some blocks_agent functions

---
 src/voxels/blocks_agent.hpp | 65 +++++++++++++++++++++++++++++++++++--
 1 file changed, 62 insertions(+), 3 deletions(-)

diff --git a/src/voxels/blocks_agent.hpp b/src/voxels/blocks_agent.hpp
index e6e0262c..10655cdc 100644
--- a/src/voxels/blocks_agent.hpp
+++ b/src/voxels/blocks_agent.hpp
@@ -1,5 +1,7 @@
 #pragma once
 
+/// blocks_agent is set of templates but not a class to minimize OOP overhead.
+
 #include "voxel.hpp"
 #include "Block.hpp"
 #include "Chunk.hpp"
@@ -11,18 +13,31 @@
 #include "maths/voxmaths.hpp"
 
 #include <set>
+#include <stdint.h>
 #include <stdexcept>
 #include <glm/glm.hpp>
 
-/// Using templates to minimize OOP overhead
-
 namespace blocks_agent {
 
+/// @brief Get specified chunk.
+/// @tparam Storage 
+/// @param chunks 
+/// @param cx chunk grid position X
+/// @param cz chunk grid position Z
+/// @return chunk or nullptr if does not exists
 template<class Storage>
 inline Chunk* get_chunk(const Storage& chunks, int cx, int cz) {
     return chunks.getChunk(cx, cz);
 }
 
+/// @brief Get voxel at specified position.
+/// Returns nullptr if voxel does not exists. 
+/// @tparam Storage chunks storage class
+/// @param chunks chunks storage
+/// @param x position X
+/// @param y position Y
+/// @param z position Z
+/// @return voxel pointer or nullptr
 template<class Storage>
 inline voxel* get(const Storage& chunks, int32_t x, int32_t y, int32_t z) {
     if (y < 0 || y >= CHUNK_H) {
@@ -39,6 +54,14 @@ inline voxel* get(const Storage& chunks, int32_t x, int32_t y, int32_t z) {
     return &chunk->voxels[(y * CHUNK_D + lz) * CHUNK_W + lx];
 }
 
+/// @brief Get voxel at specified position.
+/// @throws std::runtime_error if voxel does not exists
+/// @tparam Storage chunks storage class
+/// @param chunks chunks storage
+/// @param x position X
+/// @param y position Y
+/// @param z position Z
+/// @return voxel reference
 template<class Storage>
 inline voxel& require(const Storage& chunks, int32_t x, int32_t y, int32_t z) {
     auto vox = get(chunks, x, y, z);
@@ -53,6 +76,14 @@ inline const Block& get_block_def(const Storage& chunks, blockid_t id) {
     return chunks.getContentIndices().blocks.require(id);
 }
 
+
+/// @brief Check if block at specified position is solid.
+/// @tparam Storage chunks storage class
+/// @param chunks chunks storage
+/// @param x position X
+/// @param y position Y
+/// @param z position Z
+/// @return true if block exists and solid
 template<class Storage>
 inline bool is_solid_at(const Storage& chunks, int32_t x, int32_t y, int32_t z) {
     if (auto vox = get(chunks, x, y, z)) {
@@ -61,6 +92,13 @@ inline bool is_solid_at(const Storage& chunks, int32_t x, int32_t y, int32_t z)
     return false;
 }
 
+/// @brief Check if block at specified position is replaceable.
+/// @tparam Storage chunks storage class
+/// @param chunks chunks storage
+/// @param x position X
+/// @param y position Y
+/// @param z position Z
+/// @return true if block exists and replaceable
 template<class Storage>
 inline bool is_replaceable_at(const Storage& chunks, int32_t x, int32_t y, int32_t z) {
     if (auto vox = get(chunks, x, y, z)) {
@@ -87,6 +125,14 @@ void set(
     blockstate state
 );
 
+/// @brief Erase extended block segments
+/// @tparam Storage chunks storage class
+/// @param chunks chunks storage
+/// @param def origin block definition
+/// @param state origin block state
+/// @param x origin position X
+/// @param y origin position Y
+/// @param z origin position Z
 template<class Storage>
 inline void erase_segments(
     Storage& chunks, const Block& def, blockstate state, int x, int y, int z
@@ -108,10 +154,23 @@ inline void erase_segments(
     }
 }
 
-static constexpr uint8_t segment_to_int(int sx, int sy, int sz) {
+/// @brief Convert segment offset to segment bits
+/// @param sx segment offset X
+/// @param sy segment offset Y
+/// @param sz segment offset Z
+/// @return segment bits
+static constexpr inline uint8_t segment_to_int(int sx, int sy, int sz) {
     return ((sx > 0) | ((sy > 0) << 1) | ((sz > 0) << 2));
 }
 
+/// @brief Restore invalid extended block segments
+/// @tparam Storage chunks storage class
+/// @param chunks chunks storage
+/// @param def origin block definition
+/// @param state origin block state
+/// @param x origin position X
+/// @param y origin position Y
+/// @param z origin position Z
 template <class Storage>
 inline void repair_segments(
     Storage& chunks, const Block& def, blockstate state, int x, int y, int z