Doxygen Support (#10)

* added doxygen target and CI/CD stage

* fixed type in CI config

* added doxygen comments

* fixed type in doxyfile

* added comments describing possible errors

.github/workflows/pipeline.yml

@@ -48,4 +48,34 @@ jobs:
       uses: codecov/[email protected]
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
-        slug: maxtek6/threadpool
+        slug: maxtek6/threadpool
+
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Install Doxygen
+      uses: ssciwr/doxygen-install@v1
+
+    - name: Install Dot
+      run: sudo apt-get update && sudo apt-get install graphviz
+
+    - name: Configure
+      run: cmake -B ${{github.workspace}}/build -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}} -DTHREADPOOL_DOCS=ON
+
+    - name: Build
+      run: cmake --build ${{github.workspace}}/build --target docs
+
+    - name: Publish
+      uses: cpina/[email protected]
+      env:
+        SSH_DEPLOY_KEY: ${{ secrets.SSH_DEPLOY_KEY }}
+      with:
+        source-directory: 'build/docs/html'
+        destination-github-username: 'maxtek6'
+        destination-repository-name: 'maxtek6.github.io'
+        user-email: [email protected]
+        target-branch: master
+        target-directory: docs/threadpool

CMakeLists.txt

@@ -4,13 +4,18 @@ project(threadpool)
 
 option(THREADPOOL_TESTS "Build test suite" off)
 option(THREADPOOL_COVER "Check code coverage" off)
+option(THREADPOOL_DOCS "Build docs" off)
 
 add_library(threadpool_a STATIC threadpool.cpp)
 target_include_directories(threadpool_a PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
 
 add_library(threadpool SHARED threadpool.cpp)
 target_include_directories(threadpool PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
 
+if(THREADPOOL_DOCS)
+    add_subdirectory(docs)
+endif()
+
 if(THREADPOOL_TESTS)
     enable_testing()
     add_subdirectory(tests)

docs/CMakeLists.txt

@@ -0,0 +1,13 @@
+find_package(Doxygen)
+
+set(doxyfile_in ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
+
+set(doxyfile ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+configure_file(${doxyfile_in} ${doxyfile} @ONLY)
+
+add_custom_target(docs
+    COMMAND ${DOXYGEN_EXECUTABLE} ${doxyfile}
+    WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
+    COMMENT "Generating API documentation with Doxygen"
+    VERBATIM)

docs/Doxyfile.in

@@ -0,0 +1,20 @@
+# Use: `doxygen -g test.txt` to generate all possible settings for this file
+
+# For modern doxygen style uncomment these three lines:
+# HTML_EXTRA_STYLESHEET = @CMAKE_CURRENT_SOURCE_DIR@/doxygen/customdoxygen.css
+# HTML_HEADER = @CMAKE_CURRENT_SOURCE_DIR@/doxygen/header.html
+# HTML_FOOTER = @CMAKE_CURRENT_SOURCE_DIR@/doxygen/footer.html
+
+# not interested build output
+QUIET                  = NO
+
+# Basic settings:
+PROJECT_NAME           = "Threadpool"
+#PROJECT_NUMBER         = @PROJECT_VERSION_MAJOR@.@PROJECT_VERSION_MINOR@.@PROJECT_VERSION_PATCH@
+INPUT                  = @PROJECT_SOURCE_DIR@
+
+FILE_PATTERNS          = *.hpp \
+                         *.md
+EXTRACT_ALL            = YES
+OUTPUT_DIRECTORY       = @CMAKE_BINARY_DIR@/docs
+USE_MDFILE_AS_MAINPAGE = README.md

threadpool.hpp

@@ -23,6 +23,12 @@
 #ifndef THREADPOOL_HPP
 #define THREADPOOL_HPP
 
+/**
+ * @file threadpool.hpp
+ * @brief Maxtek threadpool
+ * @author Max Guerrero and John R. Patek Sr.
+ */
+
 #include <algorithm>
 #include <functional>
 #include <future>
@@ -32,15 +38,45 @@
 #include <typeinfo>
 #include <vector>
 
+#ifdef _WIN32
+#define DLL_EXPORT __declspec(dllexport)
+#else
+#define DLL_EXPORT
+#endif
+
 namespace maxtek
 {
-    class threadpool
+    /**
+     * @brief threadpool
+     *
+     * @class allows tasks to be submitted and exexuted asynchronously across multiple threads.
+     */
+    class DLL_EXPORT threadpool
     {
     public:
+
+        /**
+         * @brief constructs a new threadpool
+         *
+         * @param threads number of threads to use for constructing the threadpool
+         * @exception std::runtime_error if threads is set to zero
+         */
         threadpool(size_t threads = std::thread::hardware_concurrency());
 
+        /**
+         * @brief destroys threadpool after calling shutdown if necessary
+        */
         ~threadpool();
 
+        /**
+         * @brief submits a function with its arguments to the threadpool
+         * @tparam F function signature
+         * @tparam Args function argument types
+         * @param function function signature
+         * @param args arguments to pass to the function
+         * @returns a future holding the asynchronous function result
+         * @exception std::runtime_error if the thread pool has been shut down
+        */
         template <class F, class... Args>
         std::future<std::result_of_t<F(Args...)>> submit(F &&function, Args &&...args)
         {
@@ -61,8 +97,16 @@ namespace maxtek
             return result;
         }
 
+        /**
+         * @brief check if the threadpool is active
+         * @returns true if the threadpool is active, false if it has been shut down
+        */
         bool active() const;
 
+        /**
+         * @brief shut down threadpool by joining threads and rejecting submissions
+         * @exception std::runtime_error if the thread pool has already been shut down
+        */
         void shutdown();
 
     private: