From 6d8b3331d84675a7ff49b6b5d8bd12abf436e203 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adrian=20B=C3=B6ckenkamp?= Date: Wed, 29 May 2013 13:34:12 +0200 Subject: [PATCH] doxygen: doc generation fixed Doxygen skips undesired directories and files now. In addition, the documentation of the "fail" namespace has been fixed. Note that there are still several warnings (due to incomplete documentations) in the Doxygen output. Change-Id: Idad4f1ecff453765b307fa40a5c1cebc0c2ce2bb --- cmake/Doxyfile.in | 6 +++--- cmake/doxygen.cmake | 14 +++++++++++--- cmake/gem5.cmake | 2 +- src/core/comm/ExperimentData.hpp | 5 ----- src/core/cpn/CampaignManager.hpp | 1 + src/core/cpn/Minion.hpp | 1 + src/core/sal/SimulatorController.hpp | 2 ++ src/core/sal/bochs/BochsConfig.hpp | 1 + src/core/sal/gem5/Gem5Config.hpp | 1 + src/core/sal/qemu/QEMUConfig.hpp | 1 + src/core/sal/t32/T32Config.hpp | 1 + 11 files changed, 23 insertions(+), 12 deletions(-) diff --git a/cmake/Doxyfile.in b/cmake/Doxyfile.in index f306abd4..73118661 100644 --- a/cmake/Doxyfile.in +++ b/cmake/Doxyfile.in @@ -576,7 +576,7 @@ WARN_LOGFILE = # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = @CMAKE_CURRENT_SOURCE_DIR@ +INPUT = @FAIL_DOC_SOURCE@ # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is @@ -605,7 +605,7 @@ RECURSIVE = YES # excluded from the INPUT source files. This way you can easily exclude a # subdirectory from a directory tree whose root is specified with the INPUT tag. -EXCLUDE = @FAIL_DOC_EXCLUDE@ +EXCLUDE = # The EXCLUDE_SYMLINKS tag can be used select whether or not files or # directories that are symbolic links (a Unix filesystem feature) are excluded @@ -619,7 +619,7 @@ EXCLUDE_SYMLINKS = NO # against the file with absolute path, so to exclude all test directories # for example use the pattern */test/* -EXCLUDE_PATTERNS = +EXCLUDE_PATTERNS = @FAIL_DOC_EXCLUDE_PATTERNS@ # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the diff --git a/cmake/doxygen.cmake b/cmake/doxygen.cmake index 789f4baa..8313a69f 100644 --- a/cmake/doxygen.cmake +++ b/cmake/doxygen.cmake @@ -6,20 +6,28 @@ if(DOXYGEN_FOUND) # into the doxyfile. For example, CMake will replace @PROJECT_NAME@ in # a configured file with the CMake PROJECT_NAME variable's value. -set(FAIL_DOC_OUTPUT "${PROJECT_BINARY_DIR}/doc") -set(FAIL_DOC_EXCLUDE "${PROJECT_SOURCE_DIR}/simulators ${PROJECT_SOURCE_DIR}/build ${PROJECT_SOURCE_DIR}/src/core/util/pstream.h") +set(FAIL_DOC_OUTPUT "${PROJECT_BINARY_DIR}/doc") +execute_process(COMMAND find "${PROJECT_SOURCE_DIR}/src/core/" -type d -printf "%p " + OUTPUT_VARIABLE FAIL_DOC_SOURCE) +set(FAIL_DOC_EXCLUDE_PATTERNS "*/util/pstream.h */util/optionparser/optionparser.h") file(MAKE_DIRECTORY ${FAIL_DOC_OUTPUT}) +# FIXME: The find command does not quote the paths to be processed by doxygen. That +# means, the path to your Fail* directory should not contain any blanks. configure_file(${PROJECT_SOURCE_DIR}/cmake/Doxyfile.in ${PROJECT_BINARY_DIR}/Doxyfile @ONLY} ) ## call make doc to generate documentation +set(line0 "[${PROJECT_NAME}] Generating Fail* documentation with Doxygen") +set(line1 " Directories: ${FAIL_DOC_SOURCE}") +set(line2 " Excluded patterns: ${FAIL_DOC_EXCLUDE_PATTERNS}") add_custom_target(doc ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile DEPENDS ${PROJECT_BINARY_DIR}/Doxyfile WORKING_DIRECTORY ${PROJECT_BINARY_DIR} - COMMENT "[${PROJECT_NAME}] Generating Fail* documentation with Doxygen" VERBATIM + COMMENT "${line0}\n${line1}\n${line2}" VERBATIM ) + endif(DOXYGEN_FOUND) diff --git a/cmake/gem5.cmake b/cmake/gem5.cmake index a4c59d12..a926cbc6 100644 --- a/cmake/gem5.cmake +++ b/cmake/gem5.cmake @@ -40,7 +40,7 @@ if(BUILD_GEM5) add_custom_target(gem5-allclean COMMAND @echo "Cleaning Fail* and gem5 ..." COMMAND cd "${PROJECT_BINARY_DIR}/" && make clean - COMMAND cd "${gem5_src_dir}/" && scons -c + COMMAND cd "${gem5_src_dir}/" && scons -c build/ARM ) # Build "fail" library first (will be statically linked to gem5) diff --git a/src/core/comm/ExperimentData.hpp b/src/core/comm/ExperimentData.hpp index a526e92b..efada9b0 100644 --- a/src/core/comm/ExperimentData.hpp +++ b/src/core/comm/ExperimentData.hpp @@ -1,8 +1,3 @@ -/** - * \brief This is the base class for all user-defined data types for - * experiment parameter and results. - */ - #ifndef __EXPERIMENT_DATA_HPP__ #define __EXPERIMENT_DATA_HPP__ diff --git a/src/core/cpn/CampaignManager.hpp b/src/core/cpn/CampaignManager.hpp index fd87e042..c943443b 100644 --- a/src/core/cpn/CampaignManager.hpp +++ b/src/core/cpn/CampaignManager.hpp @@ -1,4 +1,5 @@ /** + * \file CampaignManager.hpp * \brief The manager for an entire campaign */ diff --git a/src/core/cpn/Minion.hpp b/src/core/cpn/Minion.hpp index dd6da7df..732d34a9 100644 --- a/src/core/cpn/Minion.hpp +++ b/src/core/cpn/Minion.hpp @@ -1,4 +1,5 @@ /** + * \file Minion.hpp * \brief The representation of a minion. */ diff --git a/src/core/sal/SimulatorController.hpp b/src/core/sal/SimulatorController.hpp index b39066a2..fd08aeec 100644 --- a/src/core/sal/SimulatorController.hpp +++ b/src/core/sal/SimulatorController.hpp @@ -11,6 +11,8 @@ #include "SALConfig.hpp" #include "ConcreteCPU.hpp" + +/// All classes, functions, constants, etc. are encapsulated in the namespace "fail". namespace fail { // Incomplete types suffice here: diff --git a/src/core/sal/bochs/BochsConfig.hpp b/src/core/sal/bochs/BochsConfig.hpp index 2dc6a0db..93e9fc73 100644 --- a/src/core/sal/bochs/BochsConfig.hpp +++ b/src/core/sal/bochs/BochsConfig.hpp @@ -1,4 +1,5 @@ /** + * \file BochsConfig.hpp * \brief Type definitions and configuration settings for * the Bochs simulator. */ diff --git a/src/core/sal/gem5/Gem5Config.hpp b/src/core/sal/gem5/Gem5Config.hpp index 3e700860..fbac43ed 100644 --- a/src/core/sal/gem5/Gem5Config.hpp +++ b/src/core/sal/gem5/Gem5Config.hpp @@ -1,4 +1,5 @@ /** + * \file Gem5Config.hpp * \brief Type definitions and configuration settings for * the gem5 simulator. */ diff --git a/src/core/sal/qemu/QEMUConfig.hpp b/src/core/sal/qemu/QEMUConfig.hpp index 801b48ea..c47573a7 100644 --- a/src/core/sal/qemu/QEMUConfig.hpp +++ b/src/core/sal/qemu/QEMUConfig.hpp @@ -1,4 +1,5 @@ /** + * \file QEMUConfig.hpp * \brief Type definitions and configuration settings for the * qemu-system-x86_64 target backend. */ diff --git a/src/core/sal/t32/T32Config.hpp b/src/core/sal/t32/T32Config.hpp index 2a1267ca..fabbceb4 100644 --- a/src/core/sal/t32/T32Config.hpp +++ b/src/core/sal/t32/T32Config.hpp @@ -1,4 +1,5 @@ /** + * \file T32Config.hpp * \brief Type definitions and configuration settings for the * T32 target backend. */