Improve documentation

application/global.h

@@ -1,44 +1,38 @@
 #ifndef MARTCHUSUTILITY_LIBRARY_GLOBAL_H
 #define MARTCHUSUTILITY_LIBRARY_GLOBAL_H
 
-/*!
- * \def PLATFORM_WINDOWS
- * \brief Defined on Windows.
- */
-
-/*!
- * \def PLATFORM_UNIX
- * \brief Defined on any UNIX system.
- */
-
-/*!
- * \def PLATFORM_LINUX
- * \brief Defined on Linux.
- */
-
 #ifdef _WIN32
 # ifndef PLATFORM_WINDOWS
+/*!
+ * \brief Defined on Windows.
+ */
 #  define PLATFORM_WINDOWS
 # endif
 #elif __unix__
 # ifndef PLATFORM_UNIX
+/*!
+ * \brief Defined on any UNIX system.
+ */
 #  define PLATFORM_UNIX
 # endif
 #endif
 #ifdef __linux__
 # ifndef PLATFORM_LINUX
+/*!
+ * \brief Defined on Linux.
+ */
 #  define PLATFORM_LINUX
 # endif
 #endif
 
 /*!
  * \def LIB_EXPORT
- * \brief This macro marks a symbol for shared library export.
+ * \brief Marks a symbol for shared library export.
  */
 
 /*!
  * \def LIB_IMPORT
- * \brief This macro declares a symbol to be an import from a shared library.
+ * \brief Declares a symbol to be an import from a shared library.
  */
 
 /*!
@@ -60,8 +54,8 @@
 
 /*!
  * \def USE_NOTHROW
- * \brief This macro marks a function as never throwing, under no circumstances.
+ * \brief Marks a function as never throwing, under no circumstances.
- * If the function does nevertheless throw, the behaviour is undefined.
+ * \remarks If the function does nevertheless throw, the behaviour is undefined.
  */
 
 #ifndef USE_NOTHROW
@@ -74,8 +68,7 @@
 
 /*!
  * \def DECLARE_ENUM
- * \brief This macro can be used to forward declare enums without
+ * \brief Forward-declares enums without preventing lupdate to parse the file correctly.
- *        preventing lupdate to parse the file correctly.
  */
 
 #define DECLARE_ENUM(name, base) enum class name : base;

conversion/stringconversion.h

@@ -74,10 +74,9 @@ enum class EmptyPartsTreat
 
 /*!
  * \brief Splits the given \a string at the specified \a delimiter.
- *
+ * \param string The string to be splitted.
- * \param strings The string to be splitted.
  * \param delimiter Specifies the delimiter.
- * \param skipEmpty Indicates whether empty parts should be skipped.
+ * \param emptyPartsRole Specifies the treatment of empty parts.
  * \param maxParts Specifies the maximal number of parts. Values less or equal zero indicate an unlimited number of parts.
  * \tparam Container The STL-container used to return the parts.
  * \returns Returns the parts.

io/binaryreader.cpp

@@ -216,7 +216,7 @@ string BinaryReader::readMultibyteTerminatedStringLE(uint16 termination)
  * \param maxBytesToRead The maximal number of bytes to read.
  * \param termination The two byte sized big endian value to be recognized as termination.
  */
-string BinaryReader::readMultibyteTerminatedStringBE(size_t maxBytesToRead, uint16 termination)
+string BinaryReader::readMultibyteTerminatedStringBE(std::size_t maxBytesToRead, uint16 termination)
 {
     unique_ptr<char []> buff = make_unique<char []>(maxBytesToRead);
     char *delimChars = m_buffer;
@@ -240,7 +240,7 @@ string BinaryReader::readMultibyteTerminatedStringBE(size_t maxBytesToRead, uint
  * \param maxBytesToRead The maximal number of bytes to read.
  * \param termination The two byte sized little endian value to be recognized as termination.
  */
-string BinaryReader::readMultibyteTerminatedStringLE(size_t maxBytesToRead, uint16 termination)
+string BinaryReader::readMultibyteTerminatedStringLE(std::size_t maxBytesToRead, uint16 termination)
 {
     unique_ptr<char []> buff = make_unique<char []>(maxBytesToRead);
     char *delimChars = m_buffer;

io/bitreader.cpp

@@ -11,8 +11,8 @@ namespace IoUtilities {
 
 /*!
  * \brief Skips the specified number of bits without reading it.
- * \param Specifies the number of bits to skip.
+ * \param bitCount Specifies the number of bits to skip.
- * \throws Throws ios_base::failure if the end of the buffer is exceeded.
+ * \throws Throws std::ios_base::failure if the end of the buffer is exceeded.
  *         The reader becomes invalid in that case.
  */
 void BitReader::skipBits(std::size_t bitCount)

io/bitreader.h

@@ -143,10 +143,11 @@ inline std::size_t BitReader::bitsAvailable()
 
 /*!
  * \brief Resets the reader.
+ * \remarks
  *  - Does not take ownership over the specified \a buffer.
  *  - bufferSize must be equal or greather than 1.
  */
-inline void BitReader::reset(const char *buffer, size_t bufferSize)
+inline void BitReader::reset(const char *buffer, std::size_t bufferSize)
 {
     m_buffer = reinterpret_cast<const byte *>(buffer);
     m_end = reinterpret_cast<const byte *>(buffer + bufferSize);
@@ -155,6 +156,7 @@ inline void BitReader::reset(const char *buffer, size_t bufferSize)
 
 /*!
  * \brief Resets the reader.
+ * \remarks
  *  - Does not take ownership over the specified \a buffer.
  *  - \a end must be greather than \a buffer.
  */

io/path.cpp

@@ -53,7 +53,7 @@ string fileName(const string &path)
  *
  * The characters <, >, ?, !, *, |, /, :, \ and new lines are considered as invalid.
  */
-void removeInvalidChars(string &fileName)
+void removeInvalidChars(std::string &fileName)
 {
     size_t startPos = 0;
     static const char invalidPathChars[] = {'\"', '<', '>', '?', '!', '*', '|', '/', ':', '\\', '\n'};
@@ -73,7 +73,7 @@ void removeInvalidChars(string &fileName)
  * \param createApplicationDirectory Indicates wheter the application subdirectory should be created if not present.
  * \returns Returns if a settings directory could be located.
  */
-bool settingsDirectory(string &result, string applicationDirectoryName, bool createApplicationDirectory)
+bool settingsDirectory(std::string &result, std::string applicationDirectoryName, bool createApplicationDirectory)
 {
     result.clear();
     fstream pathConfigFile("path.config", ios_base::in);