Updated docstrings

src/include/kompute/Tensor.hpp

@@ -17,6 +17,9 @@ namespace kp {
 class Tensor
 {
   public:
+    /**
+     * Type for tensors created: Device allows memory to be transferred from staging buffers. Staging are host memory visible. Storage are device visible but are not set up to transfer or receive data (only for shader storage).
+     */
     enum class TensorTypes
     {
         eDevice = 0,
@@ -24,45 +27,108 @@ class Tensor
         eStorage = 2,
     };
 
+    /**
+     *  Base constructor, should not be used unless explicitly intended.
+     */
     Tensor();
 
+    /**
+     *  Default constructor with data provided which would be used to create the respective vulkan buffer and memory.
+     *
+     *  @param data Vector of data that will be used by the tensor
+     *  @param tensorType Type for the tensor which is of type TensorTypes
+     */
     Tensor(std::vector<uint32_t> data,
            TensorTypes tensorType = TensorTypes::eDevice);
 
+    /**
+     * Destructor which is in charge of freeing vulkan resources unless they have been provided externally.
+     */
     ~Tensor();
 
+    /**
+     * Initialiser creates the buffer and GPU memory.
+     */
     void init(std::shared_ptr<vk::PhysicalDevice> physicalDevice,
               std::shared_ptr<vk::Device> device,
               std::shared_ptr<vk::CommandBuffer> commandBuffer);
 
-    // Create functions
-    void createBuffer();
-
-    // Destroy/Free functions
+    /**
+     * Destroys and frees the GPU resources which include the buffer and memory.
+     */
     void freeMemoryDestroyGPUResources();
 
-    // Getter functions
+    /**
+     * Returns the vector of data currently contained by the Tensor. It is important to ensure that there is no out-of-sync data with the GPU memory.
+     *
+     * @return Vector of elements representing the data in the tensor.
+     */
     std::vector<uint32_t> data();
+    /**
+     * Returns the size/magnitude of the Tensor, which will be the total number of elements across all dimensions
+     *
+     * @return Unsigned integer representing the total number of elements
+     */
     uint32_t size();
+    /**
+     * Returns the shape of the tensor, which includes the number of dimensions and the size per dimension.
+     *
+     * @return Array containing the sizes for each dimension. Zero means respective dimension is not active.
+     */
     std::array<uint32_t, KP_MAX_DIM_SIZE> shape();
+    /**
+     * Retrieve the tensor type of the Tensor
+     *
+     * @return Tensor type of tensor
+     */
     TensorTypes tensorType();
+    /**
+     * Returns true if the tensor initialisation function has been carried out successful, which would mean that the buffer and memory will have been provisioned.
+     */
     bool isInit();
 
-    // Setters
+    /**
+     * Sets / resets the vector data of the tensor. This function does not perform any copies into GPU memory and is only performed on the host.
+     */
     void setData(const std::vector<uint32_t>& data);
 
-    // Record functions
+    /**
+     * Records a copy from the memory of the tensor provided to the current
+     * thensor. This is intended to pass memory into a processing, to perform
+     * a staging buffer transfer, or to gather output (between others).
+     */
     void recordCopyFrom(std::shared_ptr<Tensor> copyFromTensor);
-    // TODO: Explore simplifying by infering pipeline stage flag bits from
-    // access flag bits (as seems to be superset)
+
+    /**
+     * Records the buffer memory barrier into the command buffer which
+     * ensures that relevant data transfers are carried out correctly.
+     *
+     * @param srcAccessMask Access flags for source access mask
+     * @param dstAccessMask Access flags for destination access mask
+     * @param scrStageMask Pipeline stage flags for source stage mask
+     * @param dstStageMask Pipeline stage flags for destination stage mask
+     */
     void recordBufferMemoryBarrier(vk::AccessFlagBits srcAccessMask,
                                    vk::AccessFlagBits dstAccessMask,
                                    vk::PipelineStageFlagBits srcStageMask,
                                    vk::PipelineStageFlagBits dstStageMask);
 
-    // Util functions
+
+    /**
+     * Constructs a vulkan descriptor buffer info which can be used to specify
+     * and reference the underlying buffer component of the tensor without
+     * exposing it.
+     *
+     * @return Descriptor buffer info with own buffer
+     */
     vk::DescriptorBufferInfo constructDescriptorBufferInfo();
+    /**
+     * Maps data from the Host Visible GPU memory into the data vector. It requires the Tensor to be of staging type for it to work.
+     */
     void mapDataFromHostMemory();
+    /**
+     * Maps data from the data vector into the Host Visible GPU memory. It requires the tensor to be of staging type for it to work.
+     */
     void mapDataIntoHostMemory();
 
   private:
@@ -79,9 +145,11 @@ class Tensor
 
     TensorTypes mTensorType = TensorTypes::eDevice;
 
-    std::array<uint32_t, KP_MAX_DIM_SIZE> mShape; // TODO: Only 1D supported
+    std::array<uint32_t, KP_MAX_DIM_SIZE> mShape;
     bool mIsInit = false;
-    // uint32_t mDataType;
+
+    // Creates the vulkan buffer
+    void createBuffer();
 
     // Private util functions
     vk::BufferUsageFlags getBufferUsageFlags();

test/TestTensor.cpp

@@ -8,3 +8,4 @@ TEST_CASE("Tensor should have same vector as initialised") {
     kp::Tensor tensor(vec);
     REQUIRE( tensor.data() == vec );
 }
+