Sphinx and Doxygen documentation

backends/include/Support/CBindingWrapping.h

@@ -25,6 +25,10 @@
 
 #pragma once
 
+/*!
+    @brief Creates two convenience functions to reinterpret_cast an opaque
+    pointer to a pointer to a Sycl type and vice-versa.
+*/
 #define DEFINE_SIMPLE_CONVERSION_FUNCTIONS(ty, ref)                            \
     __attribute__((unused)) inline ty *unwrap(ref P)                           \
     {                                                                          \
@@ -36,7 +40,11 @@
             return reinterpret_cast<ref>(const_cast<ty*>(P));                  \
     }
 
- #define DEFINE_STDCXX_CONVERSION_FUNCTIONS(ty, ref)                           \
+/*!
+    @brief Add an overloaded unwrap to assert that a pointer can be legally
+    cast. @see DEFINE_SIMPLE_CONVERSION_FUNCTIONS()
+*/
+#define DEFINE_STDCXX_CONVERSION_FUNCTIONS(ty, ref)                            \
     DEFINE_SIMPLE_CONVERSION_FUNCTIONS(ty, ref)                                \
                                                                                \
     template<typename T>                                                       \

backends/include/dppl_data_types.h

@@ -76,17 +76,30 @@ typedef signed int ssize_t;
 
 #endif /* _MSC_VER */
 
-/* Set defaults for constants which we cannot find. */
+/*!
+    @brief Represents tha largest possible value of a 64 bit signed integer.
+*/
 #if !defined(INT64_MAX)
 # define INT64_MAX 9223372036854775807LL
 #endif
+
+/*!
+    @brief Represents tha smallest possible value of a 64 bit signed integer.
+*/
 #if !defined(INT64_MIN)
 # define INT64_MIN ((-INT64_MAX)-1)
 #endif
+
+/*!
+    @brief Represents tha largest possible value of a 64bit unsigned integer.
+*/
 #if !defined(UINT64_MAX)
 # define UINT64_MAX 0xffffffffffffffffULL
 #endif
 
+/*!
+    @brief Represents a positive expression of type float.
+*/
 #ifndef HUGE_VALF
 #define HUGE_VALF (float)HUGE_VAL
 #endif

backends/include/dppl_sycl_program_interface.h

@@ -52,6 +52,7 @@ DPPL_C_EXTERN_C_BEGIN
  *
  * @param    Ctx            An opaque pointer to a sycl::context
  * @param    IL             SPIR-V binary
+ * @param    Length         The size of the IL binary in bytes.
  * @return   A new SyclProgramRef pointer if the program creation succeeded,
  *           else returns NULL.
  */
@@ -66,7 +67,7 @@ DPPLProgram_CreateFromOCLSpirv (__dppl_keep const DPPLSyclContextRef Ctx,
  *
  * @param    Ctx            An opaque pointer to a sycl::context
  * @param    Source         OpenCL source string
- * @param    CompileOptions Extra compiler flags (refer Sycl spec.)
+ * @param    CompileOpts    Extra compiler flags (refer Sycl spec.)
  * @return   A new SyclProgramRef pointer if the program creation succeeded,
  *           else returns NULL.
  */

backends/include/dppl_sycl_queue_manager.h

@@ -56,6 +56,7 @@ __dppl_give DPPLSyclQueueRef DPPLQueueMgr_GetCurrentQueue ();
 /*!
  * @brief Get a sycl::queue object of the specified type and device id.
  *
+ * @param    BETy           A valid Sycl backend value.
  * @param    DeviceTy       The type of Sycl device (sycl_device_type)
  * @param    DNum           Device id for the device (defaults to 0)
  *

docs/.gitignore

@@ -0,0 +1,5 @@
+docs
+generated_docs
+api
+build
+conf.py

docs/CMakeLists.txt

@@ -0,0 +1,90 @@
+cmake_minimum_required(VERSION 3.18 FATAL_ERROR)
+project("Data-parallel Control (dpCtl)")
+# Add the cmake folder so the FindSphinx module is found
+set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH})
+
+find_package(Sphinx REQUIRED)
+find_package(Doxygen REQUIRED)
+find_package (Git)
+
+set(DOC_OUTPUT_DIR ${CMAKE_CURRENT_SOURCE_DIR}/generated_docs)
+if( DPCTL_DOCGEN_PREFIX )
+    message(STATUS "Generating dpCtl documents in " ${DPCTL_DOCGEN_PREFIX})
+    set(DOC_OUTPUT_DIR ${DPCTL_DOCGEN_PREFIX})
+endif()
+
+set(CURRENT_RELEASE "")
+
+# Use git describe to get latest tag name
+if (GIT_FOUND)
+    execute_process(
+        COMMAND ${GIT_EXECUTABLE} describe --tags --abbrev=0
+        RESULT_VARIABLE result
+        OUTPUT_VARIABLE CURRENT_RELEASE
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+    )
+endif (GIT_FOUND)
+
+set(DOXYGEN_INPUT_DIR ../backends)
+set(DOXYGEN_OUTPUT_DIR ${DOC_OUTPUT_DIR}/doxygen)
+set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/html/index.html)
+set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
+set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+# Replace variables inside @@ with the current values
+configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
+
+file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
+
+add_custom_command(
+    OUTPUT ${DOXYGEN_INDEX_FILE}
+    DEPENDS ${DPCTL_PUBLIC_HEADERS}
+    COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
+    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+    MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
+    COMMENT "Generating Doxygen documentation"
+    VERBATIM
+)
+
+set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
+set(SPHINX_OUTPUT_DIR ${DOC_OUTPUT_DIR}/docs)
+set(SPHINX_INDEX_FILE ${SPHINX_OUTPUT_DIR}/index.html)
+set(SPHINX_CONF_IN ${SPHINX_SOURCE}/conf.in)
+set(SPHINX_CONF_OUT ${SPHINX_SOURCE}/conf.py)
+
+# Create a conf.py by replacing variables inside @@ with the current values
+configure_file(${SPHINX_CONF_IN} ${SPHINX_CONF_OUT} @ONLY)
+
+# Only regenerate Sphinx when:
+# - Doxygen has rerun
+# - Our doc files have been updated
+# - The Sphinx config has been updated
+add_custom_command(
+    OUTPUT ${SPHINX_INDEX_FILE}
+    COMMAND
+        ${SPHINX_EXECUTABLE} -b html
+        # Tell Breathe where to find the Doxygen output
+        -Dbreathe_projects.dpCtl-CAPI=${DOXYGEN_OUTPUT_DIR}/xml
+        ${SPHINX_SOURCE} ${SPHINX_OUTPUT_DIR}
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+    DEPENDS
+    # Other docs files that can be edited manually
+    ${CMAKE_CURRENT_SOURCE_DIR}/index.rst
+    ${DOXYGEN_INDEX_FILE}
+    MAIN_DEPENDENCY ${SPHINX_CONF_OUT} ${SPHINX_CONF_IN}
+    COMMENT "Generating Sphinx documentation"
+)
+
+# Target to generate only Doxygen documentation
+add_custom_target(
+    Doxygen
+    ALL
+    DEPENDS ${DOXYGEN_INDEX_FILE}
+)
+
+# Target to generate all documentation Sphinx and Doxygen
+add_custom_target(
+    Sphinx
+    ALL
+    DEPENDS Doxygen ${SPHINX_INDEX_FILE}
+)