clean code on include (#264)

- add doxygen style annotation for include, prepare for api generate
- some clean code on include

Signed-off-by: LHT129 <[email protected]>

include/vsag/allocator.h

@@ -18,24 +18,74 @@
 
 namespace vsag {
 
+/**
+ * @class Allocator
+ * @brief An abstract base class for custom memory management.
+ *
+ * The `Allocator` class provides a standard interface for custom memory
+ * allocation, deallocation, and reallocation, supporting user define control
+ * over memory usage in applications.
+ */
 class Allocator {
 public:
-    // Return the name of the allocator.
+    /**
+     * @brief Returns the name of the allocator.
+     *
+     * This pure virtual function should be overridden to provide the name
+     * or identifier of the custom allocator implementation.
+     *
+     * @return std::string The name of the allocator.
+     */
     virtual std::string
     Name() = 0;
 
-    // Allocate a block of at least size.
+    /**
+     * @brief Allocates a block of memory.
+     *
+     * This pure virtual function should be overridden to allocate a block
+     * of memory of at least the specified size.
+     *
+     * @param size The size of the memory block to allocate.
+     * @return void* Pointer to the allocated memory block.
+     */
     virtual void*
     Allocate(size_t size) = 0;
 
-    // Deallocate previously allocated block.
+    /**
+     * @brief Deallocates a previously allocated block of memory.
+     *
+     * This pure virtual function should be overridden to deallocate a block
+     * of memory that was previously allocated by this allocator.
+     *
+     * @param p Pointer to the memory block to deallocate.
+     */
     virtual void
     Deallocate(void* p) = 0;
 
-    // Reallocate the previously allocated block with long size.
+    /**
+     * @brief Reallocates a previously allocated block with a new size.
+     *
+     * This pure virtual function should be overridden to resize a block of
+     * memory that was previously allocated by this allocator.
+     *
+     * @param p Pointer to the memory block to reallocate.
+     * @param size The new size of the memory block.
+     * @return void* Pointer to the reallocated memory block.
+     */
     virtual void*
     Reallocate(void* p, size_t size) = 0;
 
+    /**
+     * @brief Constructs a new object of type T.
+     *
+     * This template function allocates memory for an object of type T and
+     * constructs it using the provided arguments.
+     *
+     * @tparam T The type of the object to construct.
+     * @tparam Args The types of the arguments for the constructor of T.
+     * @param args The arguments to pass to the constructor of T.
+     * @return T* Pointer to the newly constructed object.
+     */
     template <typename T, typename... Args>
     T*
     New(Args&&... args) {
@@ -48,6 +98,15 @@ class Allocator {
         }
     }
 
+    /**
+     * @brief Destroys an object of type T and deallocates its memory.
+     *
+     * This template function calls the destructor of an object of type T
+     * and deallocates the memory it occupies.
+     *
+     * @tparam T The type of the object to destroy.
+     * @param p Pointer to the object to destroy.
+     */
     template <typename T>
     void
     Delete(T* p) {

include/vsag/binaryset.h

@@ -19,26 +19,48 @@
 #include <set>
 #include <string>
 #include <unordered_map>
+#include <utility>
 #include <vector>
 
 namespace vsag {
-
+/**
+ * @struct Binary
+ * @brief A structure representing binary data and its size.
+ */
 struct Binary {
-    std::shared_ptr<int8_t[]> data;
-    size_t size = 0;
+    std::shared_ptr<int8_t[]> data;  ///< The binary data.
+    size_t size = 0;                 ///< The size of the binary data.
 };
 
+/**
+ * @class BinarySet
+ * @brief A class to store and manage Binary objects. Always used for serialize
+ */
 class BinarySet {
 public:
+    /// Default constructor.
     BinarySet() = default;
 
+    /// Default destructor.
     ~BinarySet() = default;
 
+    /**
+     * @brief Stores a Binary object with a specified name.
+     *
+     * @param name The name associated with the Binary object.
+     * @param binary The Binary object to be stored.
+     */
     void
     Set(const std::string& name, Binary binary) {
-        data_[name] = binary;
+        data_[name] = std::move(binary);
     }
 
+    /**
+     * @brief Retrieves a Binary object by name.
+     *
+     * @param name The name associated with the Binary object.
+     * @return The Binary object retrieved, or an empty Binary object if not found.
+     */
     Binary
     Get(const std::string& name) const {
         if (data_.find(name) == data_.end()) {
@@ -47,24 +69,37 @@ class BinarySet {
         return data_.at(name);
     }
 
+    /**
+     * @brief Gets a list of all stored names.
+     *
+     * @return A vector of all names in the BinarySet.
+     */
     std::vector<std::string>
     GetKeys() const {
         std::vector<std::string> keys;
         keys.resize(data_.size());
-        transform(
-            data_.begin(), data_.end(), keys.begin(), [](std::pair<std::string, Binary> pair) {
-                return pair.first;
-            });
+
+        std::transform(data_.begin(),
+                       data_.end(),
+                       keys.begin(),
+                       [](const std::pair<std::string, Binary>& pair) { return pair.first; });
+
         return keys;
     }
 
+    /**
+     * @brief Checks if a Binary object with the specified name exists.
+     *
+     * @param key The name of the Binary object to check for.
+     * @return True if the Binary object exists, false otherwise.
+     */
     bool
     Contains(const std::string& key) const {
         return data_.find(key) != data_.end();
     }
 
 private:
-    std::unordered_map<std::string, Binary> data_;
+    std::unordered_map<std::string, Binary> data_;  ///< The map storing Binary objects by name.
 };
 
 }  // namespace vsag

include/vsag/bitset.h

@@ -26,53 +26,63 @@ using BitsetPtr = std::shared_ptr<Bitset>;
 class Bitset {
 public:
     /**
-      * Generate a random bitset with specified length, indices start from 0.
-      * 
-      * @param length means the number of bit
-      * @return a random bitset
-      */
+     * @brief Generate a random bitset with specified length, indices start from 0.
+     *
+     * @param length The number of bits in the bitset.
+     * @return BitsetPtr A shared pointer to the generated random bitset.
+     */
     static BitsetPtr
     Random(int64_t length);
 
     /**
-      * Create an empty bitset object.
-      * 
-      * @return the bitset
-      */
+     * @brief Create an empty bitset object.
+     *
+     * @return BitsetPtr A shared pointer to the created empty bitset.
+     */
     static BitsetPtr
     Make();
 
+    Bitset(const Bitset&) = delete;
+    Bitset(Bitset&&) = delete;
+
 protected:
     Bitset() = default;
     virtual ~Bitset() = default;
 
-    Bitset(const Bitset&) = delete;
-    Bitset(Bitset&&) = delete;
-
 public:
     /**
-      * Set one bit to specified value.
-      * 
-      * @param pos the position of the bit to set
-      * @param value the value to set the bit to
-      */
+     * @brief Set one bit to specified value.
+     *
+     * @param pos The position of the bit to set.
+     * @param value The value to set the bit to (true or false).
+     */
     virtual void
-    Set(int64_t pos, bool value = true) = 0;
+    Set(int64_t pos, bool value) = 0;
 
     /**
-      * Return the value of the bit at position.
-      * 
-      * @param pos the position of bit to return
-      * @return true if the bit is set, false otherwise
-      */
+     * @brief Set one bit to true.
+     *
+     * @param pos The position of the bit to set.
+     */
+    void
+    Set(int64_t pos) {
+        return Set(pos, true);
+    }
+
+    /**
+     * @brief Return the value of the bit at a specific position.
+     *
+     * @param pos The position of the bit.
+     * @return true If the bit is set (true), false otherwise.
+     */
     virtual bool
     Test(int64_t pos) = 0;
 
     /**
-      * Returns the number of bits that set to true
-      * 
-      * @return the number of bit that set to true
-      */
+     * @brief Returns the number of bits that are set to true.
+     *
+     * @return uint64_t The number of bits set to true.
+     */
     virtual uint64_t
     Count() = 0;