Browse Source

Improve doxygen documentation

pull/1/head
Daniel Scharrer 14 years ago
parent
commit
6f2dcefd43
  1. 5
      CMakeLists.txt
  2. 36
      doc/Doxyfile.in
  3. 3
      src/cli/main.cpp
  4. 6
      src/cli/version.cpp.in
  5. 3
      src/cli/version.hpp
  6. 4
      src/loader/exereader.cpp
  7. 21
      src/loader/exereader.hpp
  8. 35
      src/loader/offsets.hpp
  9. 33
      src/util/flags.hpp

5
CMakeLists.txt

@ -160,8 +160,9 @@ include_directories(src ${CMAKE_CURRENT_BINARY_DIR})
configure_file("src/configure.hpp.in" "configure.hpp") configure_file("src/configure.hpp.in" "configure.hpp")
set(VERSION_FILE "${CMAKE_BINARY_DIR}/version.cpp") file(MAKE_DIRECTORY "${CMAKE_BINARY_DIR}/cli")
version_file("src/version.cpp.in" "${VERSION_FILE}" "VERSION" ".git") 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}") list(APPEND INNOEXTRACT_SOURCES "${VERSION_FILE}")
add_executable(innoextract ${INNOEXTRACT_SOURCES} ${ALL_INCLUDES}) add_executable(innoextract ${INNOEXTRACT_SOURCES} ${ALL_INCLUDES})

36
doc/Doxyfile.in

@ -161,7 +161,7 @@ SHORT_NAMES = NO
# comments will behave just like regular Qt-style comments # comments will behave just like regular Qt-style comments
# (thus requiring an explicit @brief command for a brief description.) # (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 # If the QT_AUTOBRIEF tag is set to YES then Doxygen will
# interpret the first line (until the first dot) of a Qt-style # 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 # will behave just like regular Qt-style comments (thus requiring
# an explicit \brief command for a brief description.) # 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 # 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 /// # 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. # 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. # 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 # 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". # 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:". # 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. # You can put \n's in the value part of an alias to insert newlines.
ALIASES = ALIASES = pname{1}="<strong class="paramname">\1</strong>"
# This tag can be used to specify a number of word-keyword mappings (TCL only). # 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 # 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 # (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. # 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 # If MARKDOWN_SUPPORT is enabled (the default) then doxygen pre-processes all
# comments according to the Markdown format, which allows for more readable # 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 # in case and if your file system supports case sensitive file names. Windows
# and Mac users are advised to set this option to NO. # 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 # 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 # 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 # alphabetically by member name. If set to NO the members will appear in
# declaration order. # 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 # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the
# brief documentation of file, namespace and class members alphabetically # 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 # 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. # 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 # 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 # 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 # wrong or incomplete parameter documentation, but not about the absence of
# documentation. # documentation.
WARN_NO_PARAMDOC = NO WARN_NO_PARAMDOC = YES
# The WARN_FORMAT tag determines the format of the warning messages that # The WARN_FORMAT tag determines the format of the warning messages that
# doxygen can produce. The string should contain the $file, $line, and $text # doxygen can produce. The string should contain the $file, $line, and $text
@ -713,7 +713,9 @@ FILE_PATTERNS = *.c \
*.f90 \ *.f90 \
*.f \ *.f \
*.vhd \ *.vhd \
*.vhdl *.vhdl \
*.hpp.in \
*.cpp.in
# The RECURSIVE tag can be used to turn specify whether or not subdirectories # 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. # 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, # wildcard * is used, a substring. Examples: ANamespace, AClass,
# AClass::ANamespace, ANamespace::*Test # AClass::ANamespace, ANamespace::*Test
EXCLUDE_SYMBOLS = EXCLUDE_SYMBOLS = boost
# The EXAMPLE_PATH tag can be used to specify one or more files or # The EXAMPLE_PATH tag can be used to specify one or more files or
# directories that contain example code fragments that are included (see # 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 # 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. # 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 # 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 # 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 # contain include files that are not input files but should be processed by
# the preprocessor. # the preprocessor.
INCLUDE_PATH = INCLUDE_PATH =
# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard # 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 # 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 # undefined via #undef or recursively expanded use the := operator
# instead of the = operator. # instead of the = operator.
PREDEFINED = PREDEFINED = HAVE_LZMA
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # 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. # 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 # HTML_FILE_EXTENSION to xhtml in order to make the SVG files
# visible in IE 9+ (other browsers do not have this requirement). # 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 # 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. # 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 # enabling this option may lead to badly anti-aliased labels on the edges of
# a graph (i.e. they become hard to read). # 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 # 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 # 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) # makes dot run faster, but since only newer versions of dot (>1.8.10)
# support this, this feature is disabled by default. # 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 # 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 # generate a legend page explaining the meaning of the various boxes and

3
src/cli/main.cpp

@ -37,9 +37,8 @@
#include <boost/filesystem/fstream.hpp> #include <boost/filesystem/fstream.hpp>
#include <boost/filesystem/operations.hpp> #include <boost/filesystem/operations.hpp>
#include "version.hpp"
#include "cli/debug.hpp" #include "cli/debug.hpp"
#include "cli/version.hpp"
#include "loader/offsets.hpp" #include "loader/offsets.hpp"

6
src/version.cpp.in → src/cli/version.cpp.in

@ -18,16 +18,14 @@
* 3. This notice may not be removed or altered from any source distribution. * 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. * 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 the exact syntax see the documentation of the configure_file() cmake command.
* For available variables see cmake/VersionString.cmake. * For available variables see cmake/VersionString.cmake.
*/ */
#cmakedefine GIT_COMMIT
#if ${BASE_VERSION_COUNT} != 3 #if ${BASE_VERSION_COUNT} != 3
#error "Configure error - the VERSION file should specify exactly two lines!" #error "Configure error - the VERSION file should specify exactly two lines!"
#endif #endif

3
src/version.hpp → src/cli/version.hpp

@ -23,10 +23,13 @@
#include <string> #include <string>
//! Name + version of the program being built
extern const std::string innoextract_version; extern const std::string innoextract_version;
//! Range of supported Inno Setup versions
extern const std::string innosetup_versions; extern const std::string innosetup_versions;
//! Copyright line for the current program
extern const std::string innoextract_copyright; extern const std::string innoextract_copyright;
#endif // INNOEXTRACT_VERSION_HPP #endif // INNOEXTRACT_VERSION_HPP

4
src/loader/exereader.cpp

@ -97,8 +97,6 @@ inline bool get_resource_table(uint32_t & entry, uint32_t resource_offset) {
return is_table; return is_table;
} }
} // anonymous namespace
uint32_t exe_reader_impl::find_resource_entry(std::istream & is, uint32_t needle) { uint32_t exe_reader_impl::find_resource_entry(std::istream & is, uint32_t needle) {
// skip: characteristics + timestamp + major version + minor version // 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; return result;
} }
} // anonymous namespace
exe_reader::resource exe_reader::find_resource(std::istream & is, uint32_t name, exe_reader::resource exe_reader::find_resource(std::istream & is, uint32_t name,
uint32_t type, uint32_t language) { uint32_t type, uint32_t language) {
return exe_reader_impl::find_resource(is, name, type, language); return exe_reader_impl::find_resource(is, name, type, language);

21
src/loader/exereader.hpp

@ -35,11 +35,12 @@ class exe_reader {
public: public:
//! Position and size of a resource entry
struct resource { 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. * \brief 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. *
* * Resources are addressed using a (\pname{name}, \pname{type}, \pname{language}) tuple.
* \param is a seekable stream to the executable file containing the resource *
* * \param is a seekable stream of the executable file containing the resource
* \return the location of the resource or (0, 0) if the requested resource does not exist. * \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, static resource find_resource(std::istream & is, uint32_t name, uint32_t type = TypeData,
uint32_t language = LanguageDefault); uint32_t language = LanguageDefault);

35
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 * 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 * warranty. In no event will the author(s) be held liable for any damages
@ -29,13 +29,13 @@
namespace loader { 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. * 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 * 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 * Inno Setup versions before \c 5.1.5 simply stored a magic number and offset to this bootstrap
* data at a fixed position (0x30) in the .exe file. * 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 * 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). * while the main setup files contains only the version and headers (header_offset is \c 0).
@ -45,24 +45,24 @@ namespace loader {
struct offsets { 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 * A value of \c 0 means there is no setup.e32 embedded in this file
*/ */
uint32_t exe_offset; 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 * A value of \c 0 means the executable size is not known
*/ */
uint32_t exe_compressed_size; 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; 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. * Currently this is either a \ref crypto::CRC32 or \ref crypto::Adler32 checksum.
*/ */
@ -72,7 +72,7 @@ struct offsets {
uint32_t message_offset; 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 * This points to a \ref setup::version followed by two compressed blocks of
* headers (see \ref stream::block_reader). * headers (see \ref stream::block_reader).
@ -85,18 +85,18 @@ struct offsets {
uint32_t header_offset; 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. * 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 * \ref stream::slice_reader provides a uniform interface to this data, no matter if it
* or split into multiple external files (slices). * is embedded or split into multiple external files (called slices).
* *
* The data is made up of multiple compressed or uncompressed chunks * The data is made up of one or more compressed or uncompressed chunks
* (see \ref stream::chunk_reader) which in turn contain the raw data for one or more file. * (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 * 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 names and meta information. * while the \ref setup::file_entry headers provide the filenames and meta information.
*/ */
uint32_t data_offset; uint32_t data_offset;
@ -106,7 +106,8 @@ struct offsets {
* Finding the headers always works - if there is no bootstrap information we assume that * Finding the headers always works - if there is no bootstrap information we assume that
* this is a file containing only the version and headers. * 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); void load(std::istream & is);

33
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 * 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 * warranty. In no event will the author(s) be held liable for any damages
@ -148,24 +148,18 @@ public:
}; };
/*! #define DECLARE_ENUM_SIZE(Enum, Size) \
* Declare a flag type using values from a given enum.
* This should always be used instead of using flags&lt;Enum&gt; 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) \
template <> \ template <> \
struct enum_size<Enum> { \ struct enum_size<Enum> { \
static const size_t value = (Size); \ static const size_t value = (Size); \
}; };
#define FLAGS_ENUM_END_HELPER(Enum) Enum ## __End #define FLAGS_ENUM_END_HELPER(Enum) Enum ## __End
#define FLAGS_ENUM_END(Enum) FLAGS_ENUM_END_HELPER(Enum) #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) \ #define DECLARE_FLAGS_OPERATORS(Flagname) \
inline Flagname operator|(Flagname::enum_type a, Flagname::enum_type b) { \ inline Flagname operator|(Flagname::enum_type a, Flagname::enum_type b) { \
@ -178,16 +172,29 @@ public:
return ~Flagname(a); \ return ~Flagname(a); \
} }
//! Get the enum name for a set of flags
#define FLAGS_ENUM(Flagname) Flagname ## __Enum #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, ...) \ #define FLAGS(Flagname, ...) \
enum FLAGS_ENUM(Flagname) { \ enum FLAGS_ENUM(Flagname) { \
__VA_ARGS__, \ __VA_ARGS__, \
FLAGS_ENUM_END(Flagname) \ FLAGS_ENUM_END(Flagname) \
}; \ }; \
typedef ::flags<FLAGS_ENUM(Flagname), FLAGS_ENUM_END(Flagname)> Flagname typedef ::flags<FLAGS_ENUM(Flagname), FLAGS_ENUM_END(Flagname)> Flagname
/*!
* Declare overloaded operators and enum_size for a flag type
*
* \param Flagname the flag to declare operators for
*/
#define FLAGS_OVERLOADS(Flagname) \ #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) DECLARE_FLAGS_OPERATORS(Flagname)
#endif // INNOEXTRACT_UTIL_FLAGS_HPP #endif // INNOEXTRACT_UTIL_FLAGS_HPP

Loading…
Cancel
Save