diff --git a/CMakeLists.txt b/CMakeLists.txt index a0dea08..530180d 100644 --- a/CMakeLists.txt +++ b/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}") diff --git a/application/argumentparser.cpp b/application/argumentparser.cpp index 129ceb5..b3b36ce 100644 --- a/application/argumentparser.cpp +++ b/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). */ diff --git a/application/failure.cpp b/application/failure.cpp index 5fe9f09..4adb8dd 100644 --- a/application/failure.cpp +++ b/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 */ diff --git a/application/fakeqtconfigarguments.cpp b/application/fakeqtconfigarguments.cpp index 17e1eca..cc81c3d 100644 --- a/application/fakeqtconfigarguments.cpp +++ b/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)") diff --git a/application/fakeqtconfigarguments.h b/application/fakeqtconfigarguments.h index 9f0d24d..1689f03 100644 --- a/application/fakeqtconfigarguments.h +++ b/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 diff --git a/cmake/modules/Doxygen.cmake b/cmake/modules/Doxygen.cmake index ba137e5..d88312b 100644 --- a/cmake/modules/Doxygen.cmake +++ b/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 -set(DOXY_LANGUAGE "English" CACHE STRING "specifies language of the API documentation generated with Doxygen") -set(DOXY_CUSTOM_CONFIG "" CACHE STRING "specifies extra options for Doxygen") -set(META_DOXY_NUMBER 1) -set(META_DOXY_LANGUAGE "${DOC_LANGUAGE}") -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 "") +else() + # load cached configuration and other variables + set(DOXY_LANGUAGE "English" CACHE STRING "specifies language of the API documentation generated with Doxygen") + set(DOXY_CUSTOM_CONFIG "" CACHE STRING "specifies extra options for Doxygen") + 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_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 -include(ListToString) -list_to_string(" " "${CMAKE_CURRENT_SOURCE_DIR}/" "${DOXY_INPUT_FILES}" DOXY_INPUT_FILES_WHITESPACE_SEPARATED) -message("string: ${DOXY_INPUT_FILES_WHITESPACE_SEPARATED}") + # convert DOXY_INPUT_FILES to whitespace-separated list + include(ListToString) + list_to_string(" " "\"${DOXY_PATH_PREFIX}" "\"" "${DOXY_INPUT_FILES}" DOXY_INPUT_FILES_WHITESPACE_SEPARATED) -# generate Doxygen configuration -configure_file( - "${DOXYGEN_TEMPLATE_FILE}" - "${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 + # generate Doxygen configuration + configure_file( + "${DOXYGEN_TEMPLATE_FILE}" + "${CMAKE_CURRENT_BINARY_DIR}/doxygen.config" ) -endforeach() -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" + # 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 + 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() diff --git a/cmake/modules/ListToString.cmake b/cmake/modules/ListToString.cmake index bf7f666..88d2b0b 100644 --- a/cmake/modules/ListToString.cmake +++ b/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}") diff --git a/cmake/templates/doxygen.in b/cmake/templates/doxygen.in index f1adcf3..c27ef50 100644 --- a/cmake/templates/doxygen.in +++ b/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 = diff --git a/io/inifile.cpp b/io/inifile.cpp index b5963b7..cc2972f 100644 --- a/io/inifile.cpp +++ b/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. */ diff --git a/io/inifile.h b/io/inifile.h index 7eb2d7f..e135c04 100644 --- a/io/inifile.h +++ b/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 > > &IniFile::data() const { diff --git a/misc/random.cpp b/misc/random.cpp index d0ca4e1..b733746 100644 --- a/misc/random.cpp +++ b/misc/random.cpp @@ -10,8 +10,8 @@ using namespace std; /*! - * \namespace MiscUtilities - * \brief Contains miscellaneous utility functions. + * \namespace RandomUtilities + * \brief Contains utility functions for generating random character sequences. */ namespace RandomUtilities { diff --git a/tests/chronotests.cpp b/tests/chronotests.cpp index 8d04bd2..777bbd7 100644 --- a/tests/chronotests.cpp +++ b/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); diff --git a/tests/conversiontests.cpp b/tests/conversiontests.cpp index d4ea0aa..3cfe98c 100644 --- a/tests/conversiontests.cpp +++ b/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); diff --git a/tests/iotests.cpp b/tests/iotests.cpp index b18fab8..f67c028 100644 --- a/tests/iotests.cpp +++ b/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); diff --git a/tests/testutils.cpp b/tests/testutils.cpp index 41ed88a..13f06b3 100644 --- a/tests/testutils.cpp +++ b/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;