Merge pull request #58 from PatKamin/generate-pages

Add script for generating API html docs

.github/workflows/docs.yml

@@ -0,0 +1,53 @@
+name: Deploy documentation to GitHub Pages
+
+on:
+  push:
+    branches: ["main"]
+
+# Cancel previous in-progress workflow, only the latest run is relevant
+concurrency:
+  group: "docs"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install doxygen
+        run: >
+          sudo apt-get update &&
+          sudo apt-get install -y doxygen
+
+      - name: Install pip requirements
+        run: python3 -m pip install -r third_party/requirements.txt
+
+      - name: Build the documentation
+        working-directory: scripts
+        run: python3 generate_docs.py
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: docs/html
+
+  deploy:
+    needs: build
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Deploy the documentation to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v3

include/umf/base.h

@@ -17,31 +17,32 @@
 extern "C" {
 #endif
 
-/// \brief Generates generic 'UMF' API versions
+/// @brief Generates generic 'UMF' API versions
 #define UMF_MAKE_VERSION(_major, _minor)                                       \
     ((_major << 16) | (_minor & 0x0000ffff))
 
-/// \brief Extracts 'UMF' API major version
+/// @brief Extracts 'UMF' API major version
 #define UMF_MAJOR_VERSION(_ver) (_ver >> 16)
 
-/// \brief Extracts 'UMF' API minor version
+/// @brief Extracts 'UMF' API minor version
 #define UMF_MINOR_VERSION(_ver) (_ver & 0x0000ffff)
 
-/// \brief Current version of the UMF headers
+/// @brief Current version of the UMF headers
 #define UMF_VERSION_CURRENT UMF_MAKE_VERSION(0, 9)
 
-/// \brief Operation results
+/// @brief Operation results
 typedef enum umf_result_t {
     UMF_RESULT_SUCCESS = 0, ///< Success
     UMF_RESULT_ERROR_OUT_OF_HOST_MEMORY =
-        1, ///< Insufficient host memory to satisfy call,
+        1, ///< Insufficient host memory to satisfy call
     UMF_RESULT_ERROR_MEMORY_PROVIDER_SPECIFIC =
-        2, ///< A provider specific warning/error has been reported and can be
-    ///< Retrieved via the umfMemoryProviderGetLastNativeError entry point.
+        2, /*!< A provider specific warning/error has been reported and can be
+              Retrieved via the umfMemoryProviderGetLastNativeError entry point. */
     UMF_RESULT_ERROR_INVALID_ARGUMENT =
         3, ///< Generic error code for invalid arguments
-    UMF_RESULT_ERROR_INVALID_ALIGNMENT = 4, /// Invalid alignment of an argument
-    UMF_RESULT_ERROR_NOT_SUPPORTED = 5,     /// Operation not supported
+    UMF_RESULT_ERROR_INVALID_ALIGNMENT =
+        4,                              ///< Invalid alignment of an argument
+    UMF_RESULT_ERROR_NOT_SUPPORTED = 5, ///< Operation not supported
 
     UMF_RESULT_ERROR_UNKNOWN = 0x7ffffffe ///< Unknown or internal error
 } umf_result_t;

include/umf/memory_pool.h

@@ -17,97 +17,105 @@
 extern "C" {
 #endif
 
+/// @brief A struct containing a memory pool handle alongside an \p ops
+///        structure containing pointers to implementations of provider-specific
+///        functions
 typedef struct umf_memory_pool_t *umf_memory_pool_handle_t;
 
 struct umf_memory_pool_ops_t;
+
+/// @brief This structure comprises function pointers used by corresponding umfPool*
+///        calls. Each memory pool implementation should initialize all function
+///        pointers.
+///
 typedef struct umf_memory_pool_ops_t umf_memory_pool_ops_t;
 
 ///
-/// \brief Creates new memory pool.
-/// \param ops instance of umf_memory_pool_ops_t
-/// \param provider memory provider that will be used for coarse-grain allocations.
-/// \param params pointer to pool-specific parameters
-/// \param hPool [out] handle to the newly created memory pool
-/// \return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+/// @brief Creates new memory pool.
+/// @param ops instance of umf_memory_pool_ops_t
+/// @param provider memory provider that will be used for coarse-grain allocations.
+/// @param params pointer to pool-specific parameters
+/// @param hPool [out] handle to the newly created memory pool
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
 ///
 umf_result_t umfPoolCreate(const umf_memory_pool_ops_t *ops,
                            umf_memory_provider_handle_t provider, void *params,
                            umf_memory_pool_handle_t *hPool);
 
 ///
-/// \brief Destroys memory pool.
-/// \param hPool handle to the pool
+/// @brief Destroys memory pool.
+/// @param hPool handle to the pool
 ///
 void umfPoolDestroy(umf_memory_pool_handle_t hPool);
 
 ///
-/// \brief Allocates size bytes of uninitialized storage of the specified hPool.
-/// \param hPool specified memory hPool
-/// \param size number of bytes to allocate
-/// \return Pointer to the allocated memory.
+/// @brief Allocates \p size bytes of uninitialized storage from \p hPool
+/// @param hPool specified memory hPool
+/// @param size number of bytes to allocate
+/// @return Pointer to the allocated memory.
 ///
 void *umfPoolMalloc(umf_memory_pool_handle_t hPool, size_t size);
 
 ///
-/// \brief Allocates size bytes of uninitialized storage of the specified hPool.
-/// with specified alignment
-/// \param hPool specified memory hPool
-/// \param size number of bytes to allocate
-/// \param alignment alignment of the allocation
-/// \return Pointer to the allocated memory.
+/// @brief Allocates \p size bytes of uninitialized storage from the specified \p hPool
+/// with the specified \p alignment
+/// @param hPool specified memory hPool
+/// @param size number of bytes to allocate
+/// @param alignment alignment of the allocation in bytes
+/// @return Pointer to the allocated memory
 ///
 void *umfPoolAlignedMalloc(umf_memory_pool_handle_t hPool, size_t size,
                            size_t alignment);
 
 ///
-/// \brief Allocates memory of the specified hPool for an array of num elements
-///        of size bytes each and initializes all bytes in the allocated storage
-///        to zero.
-/// \param hPool specified memory hPool
-/// \param num number of objects
-/// \param size specified size of each element
-/// \return Pointer to the allocated memory.
+/// @brief Allocates memory from \p hPool for an array of \p num elements
+///        of \p size bytes each and initializes all bytes in the allocated storage
+///        to zero
+/// @param hPool specified memory hPool
+/// @param num number of objects
+/// @param size number of bytes to allocate for each object
+/// @return Pointer to the allocated memory
 ///
 void *umfPoolCalloc(umf_memory_pool_handle_t hPool, size_t num, size_t size);
 
 ///
-/// \brief Reallocates memory of the specified hPool.
-/// \param hPool specified memory hPool
-/// \param ptr pointer to the memory block to be reallocated
-/// \param size new size for the memory block in bytes
-/// \return Pointer to the allocated memory.
+/// @brief Reallocates memory from \p hPool
+/// @param hPool specified memory hPool
+/// @param ptr pointer to the memory block to be reallocated
+/// @param size new size for the memory block in bytes
+/// @return Pointer to the allocated memory
 ///
 void *umfPoolRealloc(umf_memory_pool_handle_t hPool, void *ptr, size_t size);
 
 ///
-/// \brief Obtains size of block of memory allocated from the pool.
-/// \param hPool specified memory hPool
-/// \param ptr pointer to the allocated memory
-/// \return Number of bytes.
+/// @brief Obtains size of block of memory allocated from the \p hPool for a given \p ptr
+/// @param hPool specified memory hPool
+/// @param ptr pointer to the allocated memory
+/// @return size of the memory block allocated from the \p hPool
 ///
 size_t umfPoolMallocUsableSize(umf_memory_pool_handle_t hPool, void *ptr);
 
 ///
-/// \brief Frees the memory space of the specified hPool pointed by ptr.
-/// \param hPool specified memory hPool
-/// \param ptr pointer to the allocated memory
-/// \return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+/// @brief Frees the memory space of the specified \p hPool pointed by \p ptr
+/// @param hPool specified memory hPool
+/// @param ptr pointer to the allocated memory to free
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
 ///         Whether any status other than UMF_RESULT_SUCCESS can be returned
-///         depends on the memory provider used by the pool.
+///         depends on the memory provider used by the \p hPool.
 ///
 umf_result_t umfPoolFree(umf_memory_pool_handle_t hPool, void *ptr);
 
 ///
-/// \brief Frees the memory space pointed by ptr if it belongs to UMF pool, does nothing otherwise.
-/// \param ptr pointer to the allocated memory
-/// \return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+/// @brief Frees the memory space pointed by ptr if it belongs to UMF pool, does nothing otherwise.
+/// @param ptr pointer to the allocated memory
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
 ///         Whether any status other than UMF_RESULT_SUCCESS can be returned
 ///         depends on the memory provider used by the pool.
 ///
 umf_result_t umfFree(void *ptr);
 
 ///
-/// \brief Retrieve umf_result_t representing the error of the last failed allocation
+/// @brief Retrieve \p umf_result_t representing the error of the last failed allocation
 ///        operation in this thread (malloc, calloc, realloc, aligned_malloc).
 ///
 /// \details
@@ -120,24 +128,27 @@ umf_result_t umfFree(void *ptr);
 /// * The application *may* call this function from simultaneous threads.
 ///
 /// * The implementation of this function *should* be lock-free.
-/// \param hPool specified memory hPool
-/// \return Error code desciribng the failure of the last failed allocation operation.
+/// @param hPool specified memory pool handle for which the last allocation error is returned
+/// @return Error code desciribng the failure of the last failed allocation operation.
 ///         The value is undefined if the previous allocation was successful.
+///
 umf_result_t umfPoolGetLastAllocationError(umf_memory_pool_handle_t hPool);
 
 ///
-/// \brief Retrieve memory pool associated with a given ptr. Only memory allocated
+/// @brief Retrieve memory pool associated with a given ptr. Only memory allocated
 ///        with the usage of a memory provider is being tracked.
-/// \param ptr pointer to memory belonging to a memory pool
-/// \return Handle to a memory pool that contains ptr or NULL if pointer does not belong to any UMF pool.
+/// @param ptr pointer to memory belonging to a memory pool
+/// @return Handle to a memory pool that contains ptr or NULL if pointer does not belong to any UMF pool.
+///
 umf_memory_pool_handle_t umfPoolByPtr(const void *ptr);
 
 ///
-/// \brief Retrieve memory provider associated with a given pool.
-/// \param hPool specified memory pool
-/// \param hProvider [out] memory providers handle.
-/// \return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+/// @brief Retrieve memory provider associated with a given pool.
+/// @param hPool specified memory pool
+/// @param hProvider [out] memory providers handle.
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
 ///         UMF_RESULT_ERROR_INVALID_ARGUMENT if hProvider is NULL
+///
 umf_result_t umfPoolGetMemoryProvider(umf_memory_pool_handle_t hPool,
                                       umf_memory_provider_handle_t *hProvider);