Browse Source

Complete generation of API doc

- Use README.md for main page
- Add install target for API doc
- Improve some doc comments
experiment/meta_header
Martchus 6 years ago
parent
commit
d28d477ffe
  1. 4
      CMakeLists.txt
  2. 1
      application/argumentparser.cpp
  3. 2
      application/failure.cpp
  4. 9
      application/fakeqtconfigarguments.cpp
  5. 11
      application/fakeqtconfigarguments.h
  6. 76
      cmake/modules/Doxygen.cmake
  7. 4
      cmake/modules/ListToString.cmake
  8. 18
      cmake/templates/doxygen.in
  9. 5
      io/inifile.cpp
  10. 5
      io/inifile.h
  11. 4
      misc/random.cpp
  12. 3
      tests/chronotests.cpp
  13. 3
      tests/conversiontests.cpp
  14. 3
      tests/iotests.cpp
  15. 3
      tests/testutils.cpp

4
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}")

1
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).
*/

2
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
*/

9
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)")

11
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

76
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 "")
# 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}")
# 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
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(" " "\"${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}
)
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 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()

4
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}")

18
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 =

5
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.
*/

5
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.
*
* - The returned pairs represent the [scope names] and the contained "key = value"-pairs.
* \remarks 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
{

4
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 {

3
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);

3
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);

3
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);

3
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;

Loading…
Cancel
Save