Complete generation of API doc

- Use README.md for main page
- Add install target for API doc
- Improve some doc comments

CMakeLists.txt

@@ -82,6 +82,10 @@ if(MINGW)
     )
 endif()
 
+set(DOC_FILES
+    README.md
+)
+
 # required to include CMake modules from own project directory
 set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules" "${CMAKE_MODULE_PATH}")
 

application/argumentparser.cpp

@@ -656,6 +656,7 @@ void ArgumentParser::parseArgs(int argc, char *argv[])
 }
 
 /*!
+ * \class HelpArgument
  * \brief The HelpArgument class prints help information for an argument parser
  *        when present (--help, -h).
  */

application/failure.cpp

@@ -4,7 +4,7 @@ namespace ApplicationUtilities {
 
 /*!
  * \class ApplicationUtilities::Failure
- * \brief The exception that is thrown by an ArgumentParser when a parsing error occurs.
+ * \brief The Failure class is thrown by an ArgumentParser when a parsing error occurs.
  *
  * \sa ApplicationUtilities::ArgumentParser
  */

application/fakeqtconfigarguments.cpp

@@ -2,6 +2,15 @@
 
 namespace ApplicationUtilities {
 
+/*!
+ * \class FakeQtConfigArguments
+ * \brief The FakeQtConfigArguments class provides arguments for the Qt GUI used when
+ *        the application hasn't been built with Qt GUI support.
+ */
+
+/*!
+ * \brief Constructs new fake Qt-config arguments.
+ */
 FakeQtConfigArguments::FakeQtConfigArguments() :
     m_qtWidgetsGuiArg("qt-widgets-gui", "g", "shows a Qt widgets based graphical user interface (the application has not been built with Qt widgets support)"),
     m_qtQuickGuiArg("qt-quick-gui", "q", "shows a Qt quick based graphical user interface (the application has not been built with Qt quick support)")

application/fakeqtconfigarguments.h

@@ -20,16 +20,25 @@ private:
     Argument m_qtQuickGuiArg;
 };
 
+/*!
+ * \brief Returns the argument to show the Qt-widgets-based GUI.
+ */
 inline Argument &FakeQtConfigArguments::qtWidgetsGuiArg()
 {
     return m_qtWidgetsGuiArg;
 }
 
+/*!
+ * \brief Returns the argument to show the Qt-quick-based GUI.
+ */
 inline Argument &FakeQtConfigArguments::qtQuickGuiArg()
 {
     return m_qtQuickGuiArg;
 }
 
+/*!
+ * \brief Returns whether at least one of the arguments is present.
+ */
 inline bool FakeQtConfigArguments::areQtGuiArgsPresent() const
 {
     return m_qtWidgetsGuiArg.isPresent() || m_qtQuickGuiArg.isPresent();
@@ -38,7 +47,7 @@ inline bool FakeQtConfigArguments::areQtGuiArgsPresent() const
 } // namespace ApplicationUtilities
 
 #ifndef QT_CONFIG_ARGUMENTS
-#define QT_CONFIG_ARGUMENTS ApplicationUtilities::FakeQtConfigArguments
+# define QT_CONFIG_ARGUMENTS ApplicationUtilities::FakeQtConfigArguments
 #endif
 
 #endif // APPLICATIONUTILITIES_FAKEQTCONFIGARGUMENTS_H

cmake/modules/Doxygen.cmake

@@ -5,49 +5,47 @@ find_template_file("doxygen" CPP_UTILITIES DOXYGEN_TEMPLATE_FILE)
 # find executables
 find_program(DOXYGEN_BIN doxygen)
 find_program(PERL_BIN perl)
+find_program(DIA_BIN dia)
+find_program(DOT_BIN dot)
 if(NOT DOXYGEN_BIN)
     message(WARNING "Doxygen not found, unable to add target for generating API documentation.")
-endif()
 
-# load cached configuration and other variables
+else()
-set(DOXY_LANGUAGE "English" CACHE STRING "specifies language of the API documentation generated with Doxygen")
+    # load cached configuration and other variables
-set(DOXY_CUSTOM_CONFIG "" CACHE STRING "specifies extra options for Doxygen")
+    set(DOXY_LANGUAGE "English" CACHE STRING "specifies language of the API documentation generated with Doxygen")
-set(META_DOXY_NUMBER 1)
+    set(DOXY_CUSTOM_CONFIG "" CACHE STRING "specifies extra options for Doxygen")
-set(META_DOXY_LANGUAGE "${DOC_LANGUAGE}")
+    set(DOXY_NUMBER 1)
-set(DOXY_INPUT_FILES ${HEADER_FILES} ${SRC_FILES} ${TEST_HEADER_FILES} ${TEST_SRC_FILES} ${WIDGETS_HEADER_FILES} ${WIDGETS_SRC_FILES} ${QML_HEADER_FILES} ${QML_SRC_FILES})
+    set(DOXY_INPUT_FILES ${HEADER_FILES} ${SRC_FILES} ${TEST_HEADER_FILES} ${TEST_SRC_FILES} ${WIDGETS_HEADER_FILES} ${WIDGETS_SRC_FILES} ${QML_HEADER_FILES} ${QML_SRC_FILES})
-set(DOXY_OUTPUT_FILES "")
+    set(DOXY_PATH_PREFIX "${CMAKE_CURRENT_SOURCE_DIR}/")
+    list(GET DOC_FILES 0 DOXY_MAIN_PAGE_FILE)
+    set(DOXY_MAIN_PAGE_FILE "${DOXY_PATH_PREFIX}${DOXY_MAIN_PAGE_FILE}")
 
-# convert DOXY_INPUT_FILES to whitespace-separated list
+    # convert DOXY_INPUT_FILES to whitespace-separated list
-include(ListToString)
+    include(ListToString)
-list_to_string(" " "${CMAKE_CURRENT_SOURCE_DIR}/" "${DOXY_INPUT_FILES}" DOXY_INPUT_FILES_WHITESPACE_SEPARATED)
+    list_to_string(" " "\"${DOXY_PATH_PREFIX}" "\"" "${DOXY_INPUT_FILES}" DOXY_INPUT_FILES_WHITESPACE_SEPARATED)
-message("string: ${DOXY_INPUT_FILES_WHITESPACE_SEPARATED}")
 
-# generate Doxygen configuration
+    # generate Doxygen configuration
-configure_file(
+    configure_file(
-    "${DOXYGEN_TEMPLATE_FILE}"
+        "${DOXYGEN_TEMPLATE_FILE}"
-    "${CMAKE_CURRENT_BINARY_DIR}/doxygen.config"
+        "${CMAKE_CURRENT_BINARY_DIR}/doxygen.config"
-)
-
-# add target for generating API documentation
-add_custom_target(${META_PROJECT_NAME}_apidoc
-    COMMAND "${DOXYGEN_BIN}" "${CMAKE_CURRENT_BINARY_DIR}/doxygen.config"
-    SOURCES ${DOXY_INPUT_FILES}
-)
-
-# add install target for API documentation
-# TODO
-
-foreach(API_DOC_OUTPUT_FILE ${API_DOC_OUTPUT_FILES})
-    get_filename_component(API_DOC_OUTPUT_DIR ${API_DOC_OUTPUT_FILE} DIRECTORY)
-    install(
-        FILES ${API_DOC_OUTPUT_FILE}
-        DESTINATION share/${META_PROJECT_NAME}/${API_DOC_OUTPUT_DIR}
-        COMPONENT cmake-modules
     )
-endforeach()
 
-if(NOT TARGET install-api-doc)
+    # add target for generating API documentation
-    add_custom_target(install-api-doc
+    add_custom_target(${META_PROJECT_NAME}_apidoc
-        COMMAND "${CMAKE_COMMAND}" -DCMAKE_INSTALL_COMPONENT=api-doc -P "${CMAKE_BINARY_DIR}/cmake_install.cmake"
+        COMMAND "${DOXYGEN_BIN}" "${CMAKE_CURRENT_BINARY_DIR}/doxygen.config"
+        SOURCES ${DOXY_INPUT_FILES}
     )
+
+    # add install target for API documentation
+    install(DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/api-doc"
+            DESTINATION "share/${META_PROJECT_NAME}"
+            COMPONENT api-doc
+    )
+
+    if(NOT TARGET install-api-doc)
+        add_custom_target(install-api-doc
+            COMMAND "${CMAKE_COMMAND}" -DCMAKE_INSTALL_COMPONENT=api-doc -P "${CMAKE_BINARY_DIR}/cmake_install.cmake"
+        )
+    endif()
+
 endif()

cmake/modules/ListToString.cmake

@@ -1,6 +1,6 @@
 if(NOT DEFINED LIST_TO_STRING_EXISTS)
     set(LIST_TO_STRING_EXISTS true)
-    function(list_to_string separator prefix input_list output_string_var)
+    function(list_to_string separator prefix suffix input_list output_string_var)
         set(res "")
         # get list length
         list(LENGTH input_list list_length)
@@ -14,7 +14,7 @@ if(NOT DEFINED LIST_TO_STRING_EXISTS)
                 list(GET input_list ${index} item_value)
                 if(NOT item_value STREQUAL "")
                     # .. and append non-empty value to output string
-                    set(res "${res}${prefix}${item_value}")
+                    set(res "${res}${prefix}${item_value}${suffix}")
                     # append separator if current element is NOT the last one.
                     if(NOT index EQUAL last_element_index)
                         set(res "${res}${separator}")

cmake/templates/doxygen.in

@@ -1,19 +1,19 @@
 DOXYFILE_ENCODING      = UTF-8
 PROJECT_NAME           = "@META_APP_NAME@"
-PROJECT_NUMBER         = "@META_DOXY_NUMBER@"
+PROJECT_NUMBER         = "@DOXY_NUMBER@"
 PROJECT_BRIEF          = "@META_APP_DESCRIPTION@"
-PROJECT_LOGO           = "@META_DOXY_LOGO@"
+PROJECT_LOGO           = "@DOXY_LOGO@"
 OUTPUT_DIRECTORY       = "@CMAKE_CURRENT_BINARY_DIR@/api-doc"
 CREATE_SUBDIRS         = NO
 ALLOW_UNICODE_NAMES    = NO
-OUTPUT_LANGUAGE        = "@META_DOXY_LANGUAGE@"
+OUTPUT_LANGUAGE        = "@DOXY_LANGUAGE@"
 BRIEF_MEMBER_DESC      = YES
 REPEAT_BRIEF           = YES
 ABBREVIATE_BRIEF       =
 ALWAYS_DETAILED_SEC    = NO
 INLINE_INHERITED_MEMB  = NO
 FULL_PATH_NAMES        = YES
-STRIP_FROM_PATH        =
+STRIP_FROM_PATH        = "@DOXY_PATH_PREFIX@"
 STRIP_FROM_INC_PATH    =
 SHORT_NAMES            = NO
 JAVADOC_AUTOBRIEF      = NO
@@ -84,7 +84,7 @@ WARN_IF_DOC_ERROR      = YES
 WARN_NO_PARAMDOC       = NO
 WARN_FORMAT            = "$file:$line: $text"
 WARN_LOGFILE           =
-INPUT                  = @DOXY_INPUT_FILES_WHITESPACE_SEPARATED@
+INPUT                  = "@DOXY_MAIN_PAGE_FILE@" @DOXY_INPUT_FILES_WHITESPACE_SEPARATED@
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          = 
 RECURSIVE              = NO
@@ -100,7 +100,7 @@ INPUT_FILTER           =
 FILTER_PATTERNS        =
 FILTER_SOURCE_FILES    = NO
 FILTER_SOURCE_PATTERNS =
-USE_MDFILE_AS_MAINPAGE =
+USE_MDFILE_AS_MAINPAGE = "@DOXY_MAIN_PAGE_FILE@"
 SOURCE_BROWSER         = YES
 INLINE_SOURCES         = NO
 STRIP_CODE_COMMENTS    = YES
@@ -131,7 +131,7 @@ GENERATE_DOCSET        = NO
 DOCSET_FEEDNAME        = "Doxygen generated docs"
 DOCSET_BUNDLE_ID       = org.doxygen.Project
 DOCSET_PUBLISHER_ID    = org.doxygen.Publisher
-DOCSET_PUBLISHER_NAME  = Publisher
+DOCSET_PUBLISHER_NAME  = "@META_APP_AUTHOR@"
 GENERATE_HTMLHELP      = NO
 CHM_FILE               =
 HHC_LOCATION           =
@@ -222,7 +222,7 @@ EXTERNAL_PAGES         = YES
 PERL_PATH              = @PERL_BIN@
 CLASS_DIAGRAMS         = YES
 MSCGEN_PATH            =
-DIA_PATH               =
+DIA_PATH               = @DIA_BIN@
 HIDE_UNDOC_RELATIONS   = YES
 HAVE_DOT               = YES
 DOT_NUM_THREADS        = 4
@@ -243,7 +243,7 @@ GRAPHICAL_HIERARCHY    = YES
 DIRECTORY_GRAPH        = YES
 DOT_IMAGE_FORMAT       = svg
 INTERACTIVE_SVG        = YES
-DOT_PATH               =
+DOT_PATH               = @DOT_BIN@
 DOTFILE_DIRS           =
 MSCFILE_DIRS           =
 DIAFILE_DIRS           =

io/inifile.cpp

@@ -6,6 +6,11 @@ using namespace std;
 
 namespace IoUtilities {
 
+/*!
+ * \class IniFile
+ * \brief The IniFile class parses and makes INI files.
+ */
+
 /*!
  * \brief Parses all data from the specified \a inputStream.
  */

io/inifile.h

@@ -31,7 +31,7 @@ inline IniFile::IniFile()
 
 /*!
  * \brief Returns the data of the file.
- *
+ * \remarks
  *  - The returned pairs represent the [scope names] and the contained "key = value"-pairs.
  *  - The data might be modified and then saved using the make() method.
  */
@@ -42,8 +42,7 @@ inline std::vector<std::pair<std::string, std::multimap<std::string, std::string
 
 /*!
  * \brief Returns the data of the file.
- *
+ * \remarks The returned pairs represent the [scope names] and the contained "key = value"-pairs.
- *  - The returned pairs represent the [scope names] and the contained "key = value"-pairs.
  */
 inline const std::vector<std::pair<std::string, std::multimap<std::string, std::string> > > &IniFile::data() const
 {

misc/random.cpp

@@ -10,8 +10,8 @@
 using namespace std;
 
 /*!
- * \namespace MiscUtilities
+ * \namespace RandomUtilities
- * \brief Contains miscellaneous utility functions.
+ * \brief Contains utility functions for generating random character sequences.
  */
 
 namespace RandomUtilities {

tests/chronotests.cpp

@@ -14,6 +14,9 @@ using namespace ChronoUtilities;
 
 using namespace CPPUNIT_NS;
 
+/*!
+ * \brief The ChronoTests class tests classes and methods of the ChronoUtilities namespace.
+ */
 class ChronoTests : public TestFixture
 {
     CPPUNIT_TEST_SUITE(ChronoTests);

tests/conversiontests.cpp

@@ -14,6 +14,9 @@ using namespace ConversionUtilities;
 
 using namespace CPPUNIT_NS;
 
+/*!
+ * \brief The ConversionTests class tests classes and methods of the ConversionUtilities namespace.
+ */
 class ConversionTests : public TestFixture
 {
     CPPUNIT_TEST_SUITE(ConversionTests);

tests/iotests.cpp

@@ -18,6 +18,9 @@ using namespace IoUtilities;
 
 using namespace CPPUNIT_NS;
 
+/*!
+ * \brief The IoTests class tests classes and methods of the IoUtilities namespace.
+ */
 class IoTests : public TestFixture
 {
     CPPUNIT_TEST_SUITE(IoTests);

tests/testutils.cpp

@@ -14,6 +14,9 @@ using namespace std;
 using namespace ApplicationUtilities;
 using namespace ConversionUtilities;
 
+/*!
+ * \brief Contains classes and functions utilizing creating of test applications.
+ */
 namespace TestUtilities {
 
 TestApplication *TestApplication::m_instance = nullptr;