Merge branch '20-add-doxygen-comments-to-existing-code' into 'develop'

Resolve "Add Doxygen comments to existing code"

Closes #20

See merge request !11

CMakeLists.txt

@@ -57,3 +57,5 @@ target_include_directories(vkcv SYSTEM BEFORE PRIVATE ${vkcv_includes})
 target_link_libraries(vkcv ${vkcv_libraries})
 
 add_subdirectory(projects)
+
+include(${vkcv_config}/ext/Doxygen.cmake)

config/ext/Doxygen.cmake

+
+# check if Doxygen is installed
+find_package(Doxygen)
+
+if (DOXYGEN_FOUND)
+	# note the option ALL which allows to build the docs together with the application
+	add_custom_target( doc_doxygen ALL
+			COMMAND ${DOXYGEN_EXECUTABLE} ${PROJECT_SOURCE_DIR}/Doxyfile
+			WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
+			COMMENT "Generating API documentation with Doxygen"
+			VERBATIM )
+else (DOXYGEN_FOUND)
+	message(WARNING "Doxygen need to be installed to generate the doxygen documentation")
+endif (DOXYGEN_FOUND)

doc/.gitignore

+html/
+latex/

src/vkcv/Context.cpp

+/**
+ * @authors Tobias Frisch, Vanessa Karolek, Katharina Krämer, Sebastian Gaida
+ * @file src/vkcv/Context.cpp
+ * @brief Context class to handle instance, physical-device and device
+ */
+
 #include "Context.hpp"
 #include "CoreManager.hpp"
 
@@ -135,12 +141,6 @@ namespace vkcv {
 		return m_device;
 	}
 
-	/// <summary>
-	/// All existing physical devices will be evaluated by 
-	/// </summary>
-	/// <param name="instance">The instance.</param>
-	/// <returns>The optimal physical device.</returns>
-	/// <seealso cref="Context.deviceScore">
 	vk::PhysicalDevice Context::pickPhysicalDevice(vk::Instance& instance) {
 		vk::PhysicalDevice phyDevice;
 		std::vector<vk::PhysicalDevice> devices = instance.enumeratePhysicalDevices();
@@ -165,12 +165,6 @@ namespace vkcv {
 		return phyDevice;
 	}
 
-	/// <summary>
-	/// The physical device is evaluated by three categories: discrete GPU vs. integrated GPU, amount of queues and
-	/// its abilities, and VRAM.
-	/// </summary>
-	/// <param name="physicalDevice"> The physical device. </param>
-	/// <returns></returns>
 	int Context::deviceScore(const vk::PhysicalDevice& physicalDevice) {
 		int score = 0;
 		vk::PhysicalDeviceProperties properties = physicalDevice.getProperties();
@@ -201,15 +195,6 @@ namespace vkcv {
 		return score;
 	}
 
-	/// <summary>
-	/// Creates a candidate list of queues that all meet the desired flags and then creates the maximum possible number
-	/// of queues. If the number of desired queues is not sufficient, the remaining queues are created from the next
-	/// candidate from the list.
-	/// </summary>
-	/// <param name="physicalDevice">The physical device</param>
-	/// <param name="queueCount">The amount of queues to be created</param>
-	/// <param name="queueFlags">The abilities which have to be supported by any created queue</param>
-	/// <returns></returns>
 	std::vector<vk::DeviceQueueCreateInfo> Context::getQueueCreateInfos(vk::PhysicalDevice& physicalDevice, uint32_t queueCount,std::vector<float> &qPriorities, std::vector<vk::QueueFlagBits>& queueFlags) {
 		std::vector<vk::DeviceQueueCreateInfo> queueCreateInfos;
 		std::vector<vk::QueueFamilyProperties> qFamilyProperties = physicalDevice.getQueueFamilyProperties();
@@ -242,13 +227,6 @@ namespace vkcv {
 		return queueCreateInfos;
 	}
 
-	/// <summary>
-	/// With the help of the reference <paramref name="supported"> all elements in <paramref name="check"/> checked,
-	/// if they are supported by the physical device.
-	/// </summary>
-	/// <param name="supported">The reference that can be used to check <paramref name="check"/></param>
-	/// <param name="check">The elements to be checked</param>
-	/// <returns>True, if all elements in <param name="check"> are supported</returns>
 	bool Context::checkSupport(std::vector<const char*>& supported, std::vector<const char*>& check) {
 		for (auto checkElem : check) {
 			bool found = false;
@@ -264,10 +242,6 @@ namespace vkcv {
 		return true;
 	}
 
-	/// <summary>
-	/// Gets all extensions required, i.e. GLFW and advanced debug extensions.
-	/// </summary>
-	/// <returns>The required extensions</returns>
 	std::vector<const char*> Context::getRequiredExtensions() {
 		uint32_t glfwExtensionCount = 0;
 		const char** glfwExtensions = glfwGetRequiredInstanceExtensions(&glfwExtensionCount);

src/vkcv/Context.hpp

 #pragma once
+/**
+ * @authors Tobias Frisch, Vanessa Karolek, Katharina Krämer, Sebastian Gaida
+ * @file src/vkcv/Context.hpp
+ * @brief Context class to handle instance, physical-device and device
+ */
+
 #include <vulkan/vulkan.hpp>
 
 namespace vkcv {
@@ -9,32 +15,134 @@ namespace vkcv {
 		vk::PhysicalDevice m_physicalDevice;
 		vk::Device m_device;
 
+		/**
+		 * Constructor of #Context requires an @p instance, a @p physicalDevice and a @p device.
+		 *
+		 * @param instance Vulkan-Instance
+		 * @param physicalDevice Vulkan-PhysicalDevice
+		 * @param device Vulkan-Device
+		 */
 		Context(vk::Instance instance, vk::PhysicalDevice physicalDevice, vk::Device device);
 
-
 	public:
+		/**
+		 * Copy-constructor of #Context is deleted!
+		 *
+		 * @param other Other instance of #Context
+		 */
 		Context(const Context &other) = delete;
+		
+		/**
+		 * Move-constructor of #Context uses default behavior!
+		 *
+		 * @param other Other instance of #Context
+		 */
 		Context(Context &&other) = default;
 
+		/**
+		 * Get the Vulkan handle for the instance.
+		 *
+		 * @return Vulkan-Instance
+		 */
 		[[nodiscard]]
 		const vk::Instance& getInstance() const;
 		
+		/**
+		 * Get the Vulkan handle for the physical-device.
+		 *
+		 * @return Vulkan-PhysicalDevice
+		 */
 		[[nodiscard]]
 		const vk::PhysicalDevice& getPhysicalDevice() const;
 		
+		/**
+		 * Get the Vulkan handle for the device.
+		 *
+		 * @return Vulkan-Device
+		 */
 		[[nodiscard]]
 		const vk::Device& getDevice() const;
 
+		/**
+		 * Destructor of #Context
+		 */
 		virtual ~Context();
 
+		/**
+		 * Copy-operator of #Context is deleted!
+		 *
+		 * @param other Other instance of #Context
+		 * @return Reference to itself
+		 */
 		Context& operator=(const Context &other) = delete;
+		
+		/**
+		 * Move-operator of #Context uses default behavior!
+		 *
+		 * @param other Other instance of #Context
+		 * @return Reference to itself
+		 */
 		Context& operator=(Context &&other) = default;
 
+		/**
+		 * Creates a #Context with given @p applicationName and @p applicationVersion for your application.
+		 *
+		 * It is also possible to require a specific amount of queues, ask for specific queue-flags or
+		 * extensions. This function will take care of the required arguments as best as possible.
+		 *
+		 * To pass a valid version for your application, you should use #VK_MAKE_VERSION().
+		 *
+		 * @param[in] applicationName Name of the application
+		 * @param[in] applicationVersion Version of the application
+		 * @param[in] queueCount (optional) Amount of queues which is requested
+		 * @param[in] queueFlags (optional) Requested flags of queues
+		 * @param[in] instanceExtensions (optional) Requested instance extensions
+		 * @param[in] deviceExtensions (optional) Requested device extensions
+		 * @return New instance of #Context
+		 */
 		static Context create(const char* applicationName, uint32_t applicationVersion, uint32_t queueCount = 1, std::vector<vk::QueueFlagBits> queueFlags = {}, std::vector<const char*> instanceExtensions = {}, std::vector<const char*> deviceExtensions = {});
+
+		/**
+		 * @brief With the help of the reference "supported" all elements in "check" checked,
+		 * if they are supported by the physical device.
+		 * @param supported The reference that can be used to check "check"
+		 * @param check The elements to be checked
+		 * @return True, if all elements in "check" are supported
+		*/
 		static bool checkSupport(std::vector<const char*> &supported, std::vector<const char*> &check);
+
+		/**
+		 * @brief Gets all extensions required, i.e. GLFW and advanced debug extensions.
+		 * @return The required extensions
+		*/
 		static std::vector<const char*> getRequiredExtensions();
+
+		/**
+		 * @brief All existing physical devices will be evaluated by deviceScore.
+		 * @param instance The instance
+		 * @return The optimal physical device
+		 * @see Context.deviceScore
+		*/
 		static vk::PhysicalDevice pickPhysicalDevice(vk::Instance& instance);
+
+		/**
+		 * @brief The physical device is evaluated by three categories:
+		 * discrete GPU vs. integrated GPU, amount of queues and its abilities, and VRAM.physicalDevice.
+		 * @param physicalDevice The physical device
+		 * @return Device score as integer
+		*/
 		static int deviceScore(const vk::PhysicalDevice &physicalDevice);
+
+		/**
+		 * @brief Creates a candidate list of queues that all meet the desired flags and then creates the maximum possible number
+		 * of queues. If the number of desired queues is not sufficient, the remaining queues are created from the next
+		 * candidate from the list.
+		 * @param physicalDevice The physical device
+		 * @param queueCount The amount of queues to be created
+		 * @param qPriorities 
+		 * @param queueFlags The abilities which have to be supported by any created queue
+		 * @return 
+		*/
 		static std::vector<vk::DeviceQueueCreateInfo> getQueueCreateInfos(vk::PhysicalDevice& physicalDevice, uint32_t queueCount, std::vector<float>& qPriorities, std::vector<vk::QueueFlagBits> &queueFlags);
 	};
 

src/vkcv/CoreManager.cpp

+/**
+ * @authors Sebastian Gaida
+ * @file src/vkcv/CoreManager.cpp
+ * @brief Handling of global states regarding dependencies
+ */
 
 #include "CoreManager.hpp"
 

src/vkcv/CoreManager.hpp

 #pragma once
+/**
+ * @authors Sebastian Gaida
+ * @file src/vkcv/CoreManager.hpp
+ * @brief Handling of global states regarding dependencies
+ */
 
 #include <GLFW/glfw3.h>
 #include <stdexcept>
@@ -6,11 +11,12 @@
 namespace vkcv {
 
     /**
-     * initialize GLFW if not initialized
+     * initializes glfw once and increases the counter
      */
     void initGLFW();
+
     /**
-     * terminate GLFW
+     * terminates glfw once, if it was initialized or decreases the counter
      */
     void terminateGLFW();
 }

src/vkcv/Window.cpp

+/**
+ * @authors Sebastian Gaida
+ * @file src/vkcv/Window.cpp
+ * @brief Window class to handle a basic rendering surface and input
+ */
+
 #include "Window.hpp"
 #include "CoreManager.hpp"
 

src/vkcv/Window.hpp

 #pragma once
+/**
+ * @authors Sebastian Gaida
+ * @file src/vkcv/Window.hpp
+ * @brief Window class to handle a basic rendering surface and input
+ */
 
 #define GLFW_INCLUDE_VULKAN
 #include <GLFW/glfw3.h>
@@ -7,31 +12,78 @@ namespace vkcv {
 
     class Window final {
     private:
-        explicit Window(GLFWwindow *window);
-
         GLFWwindow *m_window;
 
+        /**
+         *
+         * @param GLFWwindow of the class
+         */
+        explicit Window(GLFWwindow *window);
+
     public:
+        /**
+         * creates a GLFWwindow with the parameters in the function
+         * @param[in] windowTitle of the window
+         * @param[in] width of the window (optional)
+         * @param[in] height of the window (optional)
+         * @param[in] resizable resize ability of the window (optional)
+         * @return Window class
+         */
         static Window create(const char *windowTitle, int width = -1, int height = -1, bool resizable = false);
 
+        /**
+         * checks if the window is still open, or the close event was called
+         * This function should be changed/removed later on
+         * @return bool if the window is still open
+         */
         [[nodiscard]]
         bool isWindowOpen() const;
 
+        /**
+         * polls all events on the GLFWwindow
+         */
         static void pollEvents();
 
+        /**
+         * returns the current window
+         * @return window handle
+         */
         [[nodiscard]]
         GLFWwindow *getWindow() const;
 
+        /**
+         * gets the current window width
+         * @return int with window width
+         */
         [[nodiscard]]
         int getWidth() const;
 
+        /**
+         * gets the current window height
+         * @return int with window height
+         */
         [[nodiscard]]
         int getHeight() const;
 
+        /**
+         * Copy-operator of #Window is deleted!
+         *
+         * @param other Other instance of #Window
+         * @return Reference to itself
+         */
         Window &operator=(const Window &other) = delete;
 
+        /**
+         * Move-operator of #Window uses default behavior!
+         *
+         * @param other Other instance of #Window
+         * @return Reference to itself
+         */
         Window &operator=(Window &&other) = default;
 
+        /**
+         * Destructor of #Window, terminates GLFW
+         */
         virtual ~Window();
 
     };