From 6f2dcefd43bbd2cd7adaed3138e84ca6dfb203ab Mon Sep 17 00:00:00 2001 From: Daniel Scharrer Date: Mon, 2 Jul 2012 16:23:57 +0200 Subject: [PATCH] Improve doxygen documentation --- CMakeLists.txt | 5 +++-- doc/Doxyfile.in | 36 +++++++++++++++++++----------------- src/cli/main.cpp | 3 +-- src/{ => cli}/version.cpp.in | 6 ++---- src/{ => cli}/version.hpp | 3 +++ src/loader/exereader.cpp | 4 ++-- src/loader/exereader.hpp | 21 +++++++++++++-------- src/loader/offsets.hpp | 35 ++++++++++++++++++----------------- src/util/flags.hpp | 33 ++++++++++++++++++++------------- 9 files changed, 81 insertions(+), 65 deletions(-) rename src/{ => cli}/version.cpp.in (96%) rename src/{ => cli}/version.hpp (89%) diff --git a/CMakeLists.txt b/CMakeLists.txt index 790e6f5..c709d40 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -160,8 +160,9 @@ include_directories(src ${CMAKE_CURRENT_BINARY_DIR}) configure_file("src/configure.hpp.in" "configure.hpp") -set(VERSION_FILE "${CMAKE_BINARY_DIR}/version.cpp") -version_file("src/version.cpp.in" "${VERSION_FILE}" "VERSION" ".git") +file(MAKE_DIRECTORY "${CMAKE_BINARY_DIR}/cli") +set(VERSION_FILE "${CMAKE_BINARY_DIR}/cli/version.cpp") +version_file("src/cli/version.cpp.in" "${VERSION_FILE}" "VERSION" ".git") list(APPEND INNOEXTRACT_SOURCES "${VERSION_FILE}") add_executable(innoextract ${INNOEXTRACT_SOURCES} ${ALL_INCLUDES}) diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 07c81a5..16f4dd3 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -161,7 +161,7 @@ SHORT_NAMES = NO # comments will behave just like regular Qt-style comments # (thus requiring an explicit @brief command for a brief description.) -JAVADOC_AUTOBRIEF = NO +JAVADOC_AUTOBRIEF = YES # If the QT_AUTOBRIEF tag is set to YES then Doxygen will # interpret the first line (until the first dot) of a Qt-style @@ -169,7 +169,7 @@ JAVADOC_AUTOBRIEF = NO # will behave just like regular Qt-style comments (thus requiring # an explicit \brief command for a brief description.) -QT_AUTOBRIEF = NO +QT_AUTOBRIEF = YES # The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen # treat a multi-line C++ special comment block (i.e. a block of //! or /// @@ -194,7 +194,7 @@ SEPARATE_MEMBER_PAGES = NO # The TAB_SIZE tag can be used to set the number of spaces in a tab. # Doxygen uses this value to replace tabs by spaces in code fragments. -TAB_SIZE = 8 +TAB_SIZE = 2 # This tag can be used to specify a number of aliases that acts # as commands in the documentation. An alias has the form "name=value". @@ -203,7 +203,7 @@ TAB_SIZE = 8 # will result in a user-defined paragraph with heading "Side Effects:". # You can put \n's in the value part of an alias to insert newlines. -ALIASES = +ALIASES = pname{1}="\1" # This tag can be used to specify a number of word-keyword mappings (TCL only). # A mapping has the form "name=value". For example adding @@ -248,7 +248,7 @@ OPTIMIZE_OUTPUT_VHDL = NO # (default is Fortran), use: inc=Fortran f=C. Note that for custom extensions # you also need to set FILE_PATTERNS otherwise the files are not read by doxygen. -EXTENSION_MAPPING = h=C++ +EXTENSION_MAPPING = h=C++ cpp.in=C++ hpp.in=C++ # If MARKDOWN_SUPPORT is enabled (the default) then doxygen pre-processes all # comments according to the Markdown format, which allows for more readable @@ -444,7 +444,7 @@ INTERNAL_DOCS = NO # in case and if your file system supports case sensitive file names. Windows # and Mac users are advised to set this option to NO. -CASE_SENSE_NAMES = NO +CASE_SENSE_NAMES = YES # If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen # will show members with their full class and namespace scopes in the @@ -474,7 +474,7 @@ INLINE_INFO = YES # alphabetically by member name. If set to NO the members will appear in # declaration order. -SORT_MEMBER_DOCS = YES +SORT_MEMBER_DOCS = NO # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the # brief documentation of file, namespace and class members alphabetically @@ -612,7 +612,7 @@ CITE_BIB_FILES = # The QUIET tag can be used to turn on/off the messages that are generated # by doxygen. Possible values are YES and NO. If left blank NO is used. -QUIET = NO +QUIET = YES # The WARNINGS tag can be used to turn on/off the warning messages that are # generated by doxygen. Possible values are YES and NO. If left blank @@ -639,7 +639,7 @@ WARN_IF_DOC_ERROR = YES # wrong or incomplete parameter documentation, but not about the absence of # documentation. -WARN_NO_PARAMDOC = NO +WARN_NO_PARAMDOC = YES # The WARN_FORMAT tag determines the format of the warning messages that # doxygen can produce. The string should contain the $file, $line, and $text @@ -713,7 +713,9 @@ FILE_PATTERNS = *.c \ *.f90 \ *.f \ *.vhd \ - *.vhdl + *.vhdl \ + *.hpp.in \ + *.cpp.in # The RECURSIVE tag can be used to turn specify whether or not subdirectories # should be searched for input files as well. Possible values are YES and NO. @@ -749,7 +751,7 @@ EXCLUDE_PATTERNS = # wildcard * is used, a substring. Examples: ANamespace, AClass, # AClass::ANamespace, ANamespace::*Test -EXCLUDE_SYMBOLS = +EXCLUDE_SYMBOLS = boost # The EXAMPLE_PATH tag can be used to specify one or more files or # directories that contain example code fragments that are included (see @@ -979,7 +981,7 @@ HTML_COLORSTYLE_GAMMA = 80 # page will contain the date and time when the page was generated. Setting # this to NO can help when comparing the output of multiple runs. -HTML_TIMESTAMP = YES +HTML_TIMESTAMP = NO # If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML # documentation will contain sections that can be hidden and shown after the @@ -1532,7 +1534,7 @@ SEARCH_INCLUDES = YES # contain include files that are not input files but should be processed by # the preprocessor. -INCLUDE_PATH = +INCLUDE_PATH = # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard # patterns (like *.h and *.hpp) to filter out the header-files in the @@ -1549,7 +1551,7 @@ INCLUDE_FILE_PATTERNS = # undefined via #undef or recursively expanded use the := operator # instead of the = operator. -PREDEFINED = +PREDEFINED = HAVE_LZMA # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded. @@ -1756,7 +1758,7 @@ DIRECTORY_GRAPH = YES # HTML_FILE_EXTENSION to xhtml in order to make the SVG files # visible in IE 9+ (other browsers do not have this requirement). -DOT_IMAGE_FORMAT = png +DOT_IMAGE_FORMAT = svg # If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to # enable generation of interactive SVG images that allow zooming and panning. @@ -1810,14 +1812,14 @@ MAX_DOT_GRAPH_DEPTH = 0 # enabling this option may lead to badly anti-aliased labels on the edges of # a graph (i.e. they become hard to read). -DOT_TRANSPARENT = NO +DOT_TRANSPARENT = YES # Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output # files in one run (i.e. multiple -o and -T options on the command line). This # makes dot run faster, but since only newer versions of dot (>1.8.10) # support this, this feature is disabled by default. -DOT_MULTI_TARGETS = NO +DOT_MULTI_TARGETS = YES # If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will # generate a legend page explaining the meaning of the various boxes and diff --git a/src/cli/main.cpp b/src/cli/main.cpp index 3dcaa1d..16cb019 100644 --- a/src/cli/main.cpp +++ b/src/cli/main.cpp @@ -37,9 +37,8 @@ #include #include -#include "version.hpp" - #include "cli/debug.hpp" +#include "cli/version.hpp" #include "loader/offsets.hpp" diff --git a/src/version.cpp.in b/src/cli/version.cpp.in similarity index 96% rename from src/version.cpp.in rename to src/cli/version.cpp.in index 0093a47..f873ea8 100644 --- a/src/version.cpp.in +++ b/src/cli/version.cpp.in @@ -18,16 +18,14 @@ * 3. This notice may not be removed or altered from any source distribution. */ -#include "version.hpp" +#include "cli/version.hpp" -/*! +/* * This file is automatically processed by cmake if the version or commit id changes. * For the exact syntax see the documentation of the configure_file() cmake command. * For available variables see cmake/VersionString.cmake. */ -#cmakedefine GIT_COMMIT - #if ${BASE_VERSION_COUNT} != 3 #error "Configure error - the VERSION file should specify exactly two lines!" #endif diff --git a/src/version.hpp b/src/cli/version.hpp similarity index 89% rename from src/version.hpp rename to src/cli/version.hpp index 441ab13..f81566e 100644 --- a/src/version.hpp +++ b/src/cli/version.hpp @@ -23,10 +23,13 @@ #include +//! Name + version of the program being built extern const std::string innoextract_version; +//! Range of supported Inno Setup versions extern const std::string innosetup_versions; +//! Copyright line for the current program extern const std::string innoextract_copyright; #endif // INNOEXTRACT_VERSION_HPP diff --git a/src/loader/exereader.cpp b/src/loader/exereader.cpp index 4b6179f..ada9bc1 100644 --- a/src/loader/exereader.cpp +++ b/src/loader/exereader.cpp @@ -97,8 +97,6 @@ inline bool get_resource_table(uint32_t & entry, uint32_t resource_offset) { return is_table; } -} // anonymous namespace - uint32_t exe_reader_impl::find_resource_entry(std::istream & is, uint32_t needle) { // skip: characteristics + timestamp + major version + minor version @@ -286,6 +284,8 @@ exe_reader_impl::resource exe_reader_impl::find_resource(std::istream & is, uint return result; } +} // anonymous namespace + exe_reader::resource exe_reader::find_resource(std::istream & is, uint32_t name, uint32_t type, uint32_t language) { return exe_reader_impl::find_resource(is, name, type, language); diff --git a/src/loader/exereader.hpp b/src/loader/exereader.hpp index 9268ad9..f91ad18 100644 --- a/src/loader/exereader.hpp +++ b/src/loader/exereader.hpp @@ -35,11 +35,12 @@ class exe_reader { public: + //! Position and size of a resource entry struct resource { - uint32_t offset; //! File offset of the resource data in bytes + uint32_t offset; //!< File offset of the resource data in bytes - uint32_t size; //! Size of the resource data in bytes + uint32_t size; //!< Size of the resource data in bytes }; @@ -49,12 +50,16 @@ public: }; /*! - * Find where a resource with a given ID is stored in a MS PE/COFF executable. - * Resources are addressed using a (\param name, \param type, \param language) tuple. - * - * \param is a seekable stream to the executable file containing the resource - * - * \return the location of the resource or (0, 0) if the requested resource does not exist. + * \brief Find where a resource with a given ID is stored in a MS PE/COFF executable. + * + * Resources are addressed using a (\pname{name}, \pname{type}, \pname{language}) tuple. + * + * \param is a seekable stream of the executable file containing the resource + * \param name the user-defined name of the resource + * \param type the type of the resource + * \param language the localised variant of the resource + * + * \return the location of the resource or `(0, 0)` if the requested resource does not exist. */ static resource find_resource(std::istream & is, uint32_t name, uint32_t type = TypeData, uint32_t language = LanguageDefault); diff --git a/src/loader/offsets.hpp b/src/loader/offsets.hpp index be5cf44..8921bf7 100644 --- a/src/loader/offsets.hpp +++ b/src/loader/offsets.hpp @@ -1,5 +1,5 @@ /* - * Copyright (C) 2011 Daniel Scharrer + * Copyright (C) 2011-2012 Daniel Scharrer * * This software is provided 'as-is', without any express or implied * warranty. In no event will the author(s) be held liable for any damages @@ -29,13 +29,13 @@ namespace loader { /*! - * \brief Bootstrap data for Inno Setup installers + * Bootstrap data for Inno Setup installers * * This struct contains information used by the Inno Setup loader to bootstrap the installer. * Some of these values are not available for all Inno Setup versions * - * Inno Setup versions before 5.1.5 simply stored a magic number and offset to this bootstrap - * data at a fixed position (0x30) in the .exe file. + * Inno Setup versions before \c 5.1.5 simply stored a magic number and offset to this bootstrap + * data at a fixed position (\c 0x30) in the .exe file. * * Alternatively, there is no stored bootstrap information and data is stored in external files * while the main setup files contains only the version and headers (header_offset is \c 0). @@ -45,24 +45,24 @@ namespace loader { struct offsets { /*! - * Offset of compressed setup.e32 (the actual installer) + * Offset of compressed `setup.e32` (the actual installer code) * * A value of \c 0 means there is no setup.e32 embedded in this file */ uint32_t exe_offset; /*! - * Size of setup.e32 after compression, in bytes + * Size of `setup.e32` after compression, in bytes * * A value of \c 0 means the executable size is not known */ uint32_t exe_compressed_size; - //! Size of setup.e32 before compression, in bytes + //! Size of `setup.e32` before compression, in bytes uint32_t exe_uncompressed_size; /*! - * Checksum of setup.e32 before compression + * Checksum of `setup.e32` before compression * * Currently this is either a \ref crypto::CRC32 or \ref crypto::Adler32 checksum. */ @@ -72,7 +72,7 @@ struct offsets { uint32_t message_offset; /*! - * Offset of embedded setup-0.bin data (the setup headers) + * Offset of embedded `setup-0.bin` data (the setup headers) * * This points to a \ref setup::version followed by two compressed blocks of * headers (see \ref stream::block_reader). @@ -85,18 +85,18 @@ struct offsets { uint32_t header_offset; /*! - * Offset of embedded setup-1.bin data + * Offset of embedded `setup-1.bin` data * * A value of \c 0 means that the setup data is stored in seprarate files. * - * \ref stream::slice_reader abstracts loading this data no matter if it is embedded - * or split into multiple external files (slices). + * \ref stream::slice_reader provides a uniform interface to this data, no matter if it + * is embedded or split into multiple external files (called slices). * - * The data is made up of multiple compressed or uncompressed chunks - * (see \ref stream::chunk_reader) which in turn contain the raw data for one or more file. + * The data is made up of one or more compressed or uncompressed chunks + * (read by \ref stream::chunk_reader) which in turn each contain the raw data for one or more file. * - * The layout of the chunks and files is described in the \ref setup::data_entry headers - * while the \ref setup::file_entry headers provide the names and meta information. + * The layout of the chunks and files is stored in the \ref setup::data_entry headers + * while the \ref setup::file_entry headers provide the filenames and meta information. */ uint32_t data_offset; @@ -106,7 +106,8 @@ struct offsets { * Finding the headers always works - if there is no bootstrap information we assume that * this is a file containing only the version and headers. * - * \param is a seekable stream to the main installer file + * \param is a seekable stream of the main installer file. This should be the file + * containing the headers, which is almost always the .exe file. */ void load(std::istream & is); diff --git a/src/util/flags.hpp b/src/util/flags.hpp index 9903e44..0c735b4 100644 --- a/src/util/flags.hpp +++ b/src/util/flags.hpp @@ -1,5 +1,5 @@ /* - * Copyright (C) 2011 Daniel Scharrer + * Copyright (C) 2011-2012 Daniel Scharrer * * This software is provided 'as-is', without any express or implied * warranty. In no event will the author(s) be held liable for any damages @@ -148,24 +148,18 @@ public: }; -/*! - * Declare a flag type using values from a given enum. - * This should always be used instead of using flags<Enum> directly. - * - * \param Enum should be an enum with values that have exactly one bit set. - * \param Flagname is the name for the flag type to be defined. - */ -#define DECLARE_FLAGS_SIZE(Enum, Flagname, Size) \ +#define DECLARE_ENUM_SIZE(Enum, Size) \ template <> \ struct enum_size { \ static const size_t value = (Size); \ }; #define FLAGS_ENUM_END_HELPER(Enum) Enum ## __End #define FLAGS_ENUM_END(Enum) FLAGS_ENUM_END_HELPER(Enum) -#define DECLARE_FLAGS(Enum, Flagname) DECLARE_FLAGS_SIZE(Enum, Flagname, FLAGS_ENUM_END(Enum)) /*! - * Declare overloaded operators for a given flag type. + * Declare overloaded operators for a flag type + * + * \param Flagname the flag to declare operators for */ #define DECLARE_FLAGS_OPERATORS(Flagname) \ inline Flagname operator|(Flagname::enum_type a, Flagname::enum_type b) { \ @@ -178,16 +172,29 @@ public: return ~Flagname(a); \ } +//! Get the enum name for a set of flags #define FLAGS_ENUM(Flagname) Flagname ## __Enum + +/*! + * Declare a set of flags + * + * \param Flagname the name for the flags + * \param ... the flags to declare + */ #define FLAGS(Flagname, ...) \ enum FLAGS_ENUM(Flagname) { \ __VA_ARGS__, \ FLAGS_ENUM_END(Flagname) \ }; \ typedef ::flags Flagname - + +/*! + * Declare overloaded operators and enum_size for a flag type + * + * \param Flagname the flag to declare operators for + */ #define FLAGS_OVERLOADS(Flagname) \ - DECLARE_FLAGS_SIZE(FLAGS_ENUM(Flagname), Flagname, FLAGS_ENUM_END(Flagname)) \ + DECLARE_ENUM_SIZE(FLAGS_ENUM(Flagname), FLAGS_ENUM_END(Flagname)) \ DECLARE_FLAGS_OPERATORS(Flagname) #endif // INNOEXTRACT_UTIL_FLAGS_HPP