Improve API doc

CMakeLists.txt

@@ -149,19 +149,23 @@ set(TEST_SRC_FILES
     tests/overall.cpp
 )
 
+set(DOC_FILES
+    README.md
+)
+
 # meta data
 set(META_PROJECT_NAME tagparser)
 set(META_PROJECT_VARNAME TAG_PARSER)
 set(META_APP_NAME "Tag Parser")
 set(META_APP_AUTHOR "Martchus")
 set(META_APP_URL "https://github.com/${META_APP_AUTHOR}/${META_PROJECT_NAME}")
-set(META_APP_DESCRIPTION "C++ library for reading and writing MP4 (iTunes), ID3, Vorbis and Matroska tags.")
+set(META_APP_DESCRIPTION "C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags.")
 set(META_VERSION_MAJOR 6)
 set(META_VERSION_MINOR 0)
 set(META_VERSION_PATCH 0)
 
 # find c++utilities
-find_package(c++utilities 3.3.0 REQUIRED)
+find_package(c++utilities 4.0.0 REQUIRED)
 use_cpp_utilities()
 
 # find zlib
@@ -174,3 +178,4 @@ include(BasicConfig)
 include(WindowsResources)
 include(LibraryTarget)
 include(TestTarget)
+include(Doxygen)

README.md

@@ -39,7 +39,7 @@ API provides a way to check which encoding is present (when reading) and which e
 can be used (when writing).
 
 ## Usage
-For examples check out the command line interface of my Tag Editor (which is also on Git).
+For examples check out the command line interface of my [Tag Editor](https://github.com/Martchus/tageditor).
 
 ## Bugs, stability
 - Matroska files composed of more than one segment aren't tested yet and might not work.

abstractattachment.cpp

@@ -37,7 +37,7 @@ StreamDataBlock::StreamDataBlock() :
  *
  * The object does NOT take ownership over the stream returned by the specified function.
  */
-StreamDataBlock::StreamDataBlock(const std::function<std::istream & ()> &stream, istream::off_type startOffset, ios_base::seekdir startDir, istream::off_type endOffset, ios_base::seekdir endDir) :
+StreamDataBlock::StreamDataBlock(const std::function<std::istream & ()> &stream, std::istream::off_type startOffset, std::ios_base::seekdir startDir, std::istream::off_type endOffset, std::ios_base::seekdir endDir) :
     m_stream(stream)
 {
     auto &s = stream();

abstracttrack.cpp

@@ -75,7 +75,7 @@ AbstractTrack::AbstractTrack(istream &inputStream, ostream &outputStream, uint64
  *               information.
  * \param startOffset The start offset of the track in the specified \a stream.
  */
-AbstractTrack::AbstractTrack(iostream &stream, uint64 startOffset) :
+AbstractTrack::AbstractTrack(std::iostream &stream, uint64 startOffset) :
     AbstractTrack(stream, stream, startOffset)
 {}
 

backuphelper.cpp

@@ -58,7 +58,7 @@ string &backupDirectory()
  *
  * \throws Throws std::ios_base::failure on failure.
  */
-void restoreOriginalFileFromBackupFile(const string &originalPath, const string &backupPath, fstream &originalStream, fstream &backupStream)
+void restoreOriginalFileFromBackupFile(const std::string &originalPath, const std::string &backupPath, std::fstream &originalStream, std::fstream &backupStream)
 {
     // ensure the orignal stream is closed
     if(originalStream.is_open()) {
@@ -114,7 +114,7 @@ void restoreOriginalFileFromBackupFile(const string &originalPath, const string
  *
  * \throws Throws std::ios_base::failure on failure.
  */
-void createBackupFile(const string &originalPath, string &backupPath, fstream &originalStream, fstream &backupStream)
+void createBackupFile(const std::string &originalPath, std::string &backupPath, std::fstream &originalStream, std::fstream &backupStream)
 {
     // determine the backup path
     const string &backupDir = backupDirectory();
@@ -246,7 +246,7 @@ void createBackupFile(const string &originalPath, string &backupPath, fstream &o
  *                     no backup file has been created.
  * \param context      Specifies the context used to add notifications.
  */
-void handleFailureAfterFileModified(MediaFileInfo &fileInfo, const string &backupPath, fstream &outputStream, fstream &backupStream, const string &context)
+void handleFailureAfterFileModified(MediaFileInfo &fileInfo, const std::string &backupPath, std::fstream &outputStream, std::fstream &backupStream, const std::string &context)
 {
     // reset the associated container in any case
     if(fileInfo.container()) {

id3/id3genres.cpp

@@ -5,8 +5,8 @@ using namespace std;
 namespace Media {
 
 /*!
- * \class Media::Id3Genres
- * \brief Id3Genres converts pre-defined ID3 genres to strings and vise versa.
+ * \class Id3Genres
+ * \brief The Id3Genres class converts pre-defined ID3 genres to strings and vise versa.
  */
 
 /*!

id3/id3v1tag.cpp

@@ -40,14 +40,13 @@ bool Id3v1Tag::canEncodingBeUsed(TagTextEncoding encoding) const
 
 /*!
  * \brief Parses tag information from the specified \a stream.
- *
+ * \param stream Specifies the stream to read from.
  * \param autoSeek Specifies whether the parser should automatically seek at the end of stream.
- *
  * \throws Throws std::ios_base::failure when an IO error occurs.
  * \throws Throws Media::Failure or a derived exception when a parsing
  *         error occurs.
  */
-void Id3v1Tag::parse(istream &stream, bool autoSeek)
+void Id3v1Tag::parse(std::istream &stream, bool autoSeek)
 {
     invalidateStatus();
     static const string context("parsing ID3v1 tag");
@@ -89,7 +88,7 @@ void Id3v1Tag::parse(istream &stream, bool autoSeek)
  * \throws Throws Media::Failure or a derived exception when a parsing
  *         error occurs.
  */
-void Id3v1Tag::parse(iostream &stream)
+void Id3v1Tag::parse(std::iostream &stream)
 {
     return parse(stream, false);
 }

id3/id3v2frame.cpp

@@ -575,7 +575,7 @@ byte Id3v2Frame::makeTextEncodingByte(TagTextEncoding textEncoding)
  * \remarks The length is always returned as the number of bytes, not as the number of characters (makes a difference for
  *          UTF-16 encodings).
  */
-tuple<const char *, size_t, const char *> Id3v2Frame::parseSubstring(const char *buffer, size_t bufferSize, TagTextEncoding &encoding, bool addWarnings)
+tuple<const char *, size_t, const char *> Id3v2Frame::parseSubstring(const char *buffer, std::size_t bufferSize, TagTextEncoding &encoding, bool addWarnings)
 {
     tuple<const char *, size_t, const char *> res(buffer, 0, buffer + bufferSize);
     switch(encoding) {
@@ -684,7 +684,7 @@ void Id3v2Frame::parseBom(const char *buffer, size_t maxSize, TagTextEncoding &e
  * \param tagValue Specifies the tag value used to store the results.
  * \param typeInfo Specifies a byte used to store the type info.
  */
-void Id3v2Frame::parseLegacyPicture(const char *buffer, size_t maxSize, TagValue &tagValue, byte &typeInfo)
+void Id3v2Frame::parseLegacyPicture(const char *buffer, std::size_t maxSize, TagValue &tagValue, byte &typeInfo)
 {
     static const string context("parsing ID3v2.2 picture frame");
     if(maxSize < 6) {
@@ -711,7 +711,7 @@ void Id3v2Frame::parseLegacyPicture(const char *buffer, size_t maxSize, TagValue
  * \param tagValue Specifies the tag value used to store the results.
  * \param typeInfo Specifies a byte used to store the type info.
  */
-void Id3v2Frame::parsePicture(const char *buffer, size_t maxSize, TagValue &tagValue, byte &typeInfo)
+void Id3v2Frame::parsePicture(const char *buffer, std::size_t maxSize, TagValue &tagValue, byte &typeInfo)
 {
     static const string context("parsing ID3v2.3 picture frame");
     const char *end = buffer + maxSize;
@@ -745,7 +745,7 @@ void Id3v2Frame::parsePicture(const char *buffer, size_t maxSize, TagValue &tagV
  * \param dataSize Specifies the maximal number of bytes to read from the buffer.
  * \param tagValue Specifies the tag value used to store the results.
  */
-void Id3v2Frame::parseComment(const char *buffer, size_t dataSize, TagValue &tagValue)
+void Id3v2Frame::parseComment(const char *buffer, std::size_t dataSize, TagValue &tagValue)
 {
     static const string context("parsing comment/unsynchronized lyrics frame");
     const char *end = buffer + dataSize;
@@ -773,7 +773,7 @@ void Id3v2Frame::parseComment(const char *buffer, size_t dataSize, TagValue &tag
  * \param value Specifies the string to make.
  * \param encoding Specifies the encoding of the string to make.
  */
-void Id3v2Frame::makeString(unique_ptr<char[]> &buffer, uint32 &bufferSize, const string &value, TagTextEncoding encoding)
+void Id3v2Frame::makeString(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, const std::string &value, TagTextEncoding encoding)
 {
     makeEncodingAndData(buffer, bufferSize, encoding, value.data(), value.size());
 }
@@ -781,11 +781,12 @@ void Id3v2Frame::makeString(unique_ptr<char[]> &buffer, uint32 &bufferSize, cons
 /*!
  * \brief Writes an encoding denoation and the specified \a data to a \a buffer.
  * \param buffer Specifies the buffer.
+ * \param bufferSize Specifies the size of \a buffer.
  * \param encoding Specifies the data encoding.
  * \param data Specifies the data.
- * \param dataSize Specifies the data size.
+ * \param dataSize Specifies size of \a data.
  */
-void Id3v2Frame::makeEncodingAndData(unique_ptr<char[]> &buffer, uint32 &bufferSize, TagTextEncoding encoding, const char *data, size_t dataSize)
+void Id3v2Frame::makeEncodingAndData(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, TagTextEncoding encoding, const char *data, std::size_t dataSize)
 {
     // calculate buffer size
     if(!data) {

id3/id3v2frame.h

@@ -137,15 +137,15 @@ public:
     std::tuple<const char *, size_t, const char *> parseSubstring(const char *buffer, std::size_t maxSize, TagTextEncoding &encoding, bool addWarnings = false);
     std::string parseString(const char *buffer, std::size_t maxSize, TagTextEncoding &encoding, bool addWarnings = false);
     std::u16string parseWideString(const char *buffer, std::size_t dataSize, TagTextEncoding &encoding, bool addWarnings = false);
-    void parseLegacyPicture(const char *buffer, size_t maxSize, TagValue &tagValue, byte &typeInfo);
-    void parsePicture(const char *buffer, size_t maxSize, TagValue &tagValue, byte &typeInfo);
-    void parseComment(const char *buffer, size_t maxSize, TagValue &tagValue);
+    void parseLegacyPicture(const char *buffer, std::size_t maxSize, TagValue &tagValue, byte &typeInfo);
+    void parsePicture(const char *buffer, std::size_t maxSize, TagValue &tagValue, byte &typeInfo);
+    void parseComment(const char *buffer, std::size_t maxSize, TagValue &tagValue);
     void parseBom(const char *buffer, std::size_t maxSize, TagTextEncoding &encoding);
 
     // making helper
     byte makeTextEncodingByte(TagTextEncoding textEncoding);
     void makeString(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, const std::string &value, TagTextEncoding encoding);
-    void makeEncodingAndData(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, TagTextEncoding encoding, const char *data, size_t m_dataSize);
+    void makeEncodingAndData(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, TagTextEncoding encoding, const char *data, std::size_t m_dataSize);
     void makeLegacyPicture(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, const TagValue &picture, byte typeInfo);
     void makePicture(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, const TagValue &picture, byte typeInfo);
     void makeComment(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, const TagValue &comment);

matroska/ebmlelement.cpp

@@ -427,6 +427,8 @@ byte EbmlElement::makeUInteger(uint64 value, char *buff)
 /*!
  * \brief Writes \a value to \a buff.
  * \returns Returns the number of bytes written to \a buff.
+ * \param value Specifies the value to be written.
+ * \param buff Specifies the buffer to write to.
  * \param minBytes Specifies the minimum number of bytes to use.
  */
 byte EbmlElement::makeUInteger(uint64 value, char *buff, byte minBytes)
@@ -482,7 +484,7 @@ void EbmlElement::makeSimpleElement(ostream &stream, identifierType id, uint64 c
  * \param id Specifies the element ID.
  * \param content Specifies the value of the element as string.
  */
-void EbmlElement::makeSimpleElement(ostream &stream, GenericFileElement::identifierType id, const string &content)
+void EbmlElement::makeSimpleElement(std::ostream &stream, GenericFileElement::identifierType id, const std::string &content)
 {
     char buff1[8];
     byte sizeLength = EbmlElement::makeId(id, buff1);

matroska/matroskachapter.cpp

@@ -25,10 +25,9 @@ MatroskaChapter::~MatroskaChapter()
 /*!
  * \fn MatroskaChapter::parse()
  * \brief Parses the "ChapterAtom"-element which has been specified when constructing the object.
- *
- * Fetches nested chapters but does not parse them.
- *
- * Clears all previous parsing results.
+ * \remarks
+ * - Fetches nested chapters but does not parse them.
+ * - Clears all previous parsing results.
  */
 
 void MatroskaChapter::internalParse()

matroska/matroskaseekinfo.cpp

@@ -95,7 +95,6 @@ void MatroskaSeekInfo::parse(EbmlElement *seekHeadElement)
 /*!
  * \brief Writes a "SeekHead" element for the current instance to the specified \a stream.
  * \param stream Specifies the stream to write the "SeekHead" element to.
- * \param segmentStartOffset Specifies the start offset of "Segment" element the "SeekHead" belongs to.
  * \throws Throws ios_base::failure when an IO error occurs.
  * \throws Throws Failure or a derived exception when a making error occurs.
  */

mediafileinfo.cpp

@@ -49,6 +49,11 @@ using namespace IoUtilities;
 using namespace ConversionUtilities;
 using namespace ChronoUtilities;
 
+/*!
+ * \namespace IoUtilities
+ * \brief Contains utility classes helping to read and write streams.
+ */
+
 namespace Media {
 
 #ifdef FORCE_FULL_PARSE_DEFAULT

mediaformat.h

@@ -32,8 +32,8 @@ enum class GeneralMediaFormat
     AfxStream, /**< AFX Stream */
     Alac, /**< Apple Lossless Audio Codec */
     Als, /**< ALS */
-    Amr, /** < AMR */
-    Avc, /** < Advanced Video Coding */
+    Amr, /**< AMR */
+    Avc, /**< Advanced Video Coding */
     Bitmap, /**< Windows Bitmap */
     Dirac, /**< Dirac */
     Dts, /**< DTS */
@@ -54,7 +54,7 @@ enum class GeneralMediaFormat
     MicrosoftAudioCodecManager, /**< Microsoft Audio Codec Manager (ACM) */
     MicrosoftMpeg4, /**< Microsoft MPEG-4 */
     MicrosoftVideoCodecManager, /**< Microsoft Video Codec Manager (VCM) */
-    DolbyMlp, /** < Dolby MLP */
+    DolbyMlp, /**< Dolby MLP */
     Mpeg1Audio, /**< MPEG-1 Audio */
     Mpeg1Video, /**< MPEG-1 Vudio */
     Mpeg2Audio, /**< MPEG-2 Audio */
@@ -78,15 +78,15 @@ enum class GeneralMediaFormat
     TextSubtitle, /**< Text subtitle */
     Theora, /**< Theora */
     Tiff, /**< TIFF */
-    TimedText, /** < Timed Text */
+    TimedText, /**< Timed Text */
     Tta, /**< The True Audio lessles audio compressor */
     UncompressedVideoFrames, /**< uncompressed RGB */
     Vc1, /**< VC-1 */
     VobBtn, /**< VobBtn */
     VobSub, /**< VobSub */
     Vorbis, /**< Vorbis */
-    Vp8, /** < VP8 */
-    Vp9, /** < VP9 */
+    Vp8, /**< VP8 */
+    Vp9, /**< VP9 */
     WavPack, /**< WavPack */
     WindowsMediaAudio, /**< Windows Media Audio */
     WindowsMediaVideo, /**< Windows Media Video */

signature.h

@@ -18,12 +18,12 @@ enum class TagTargetLevel : byte;
 enum class ContainerFormat
 {
     Unknown, /**< unknown container format */
-    Adts, /** < Audio Data Transport Stream */
-    Ar, /** < "GNU ar" archive */
+    Adts, /**< Audio Data Transport Stream */
+    Ar, /**< "GNU ar" archive */
     Asf, /**< Advanced Systems Format */
-    Bzip2, /** bzip2 compressed file */
+    Bzip2, /**< bzip2 compressed file */
     Elf, /**< Executable and Linkable Format */
-    Flac, /** < Free Lossless Audio Codec (raw stream) */
+    Flac, /**< Free Lossless Audio Codec (raw stream) */
     FlashVideo, /**< Flash (FLV) */
     Gif87a, /**< Graphics Interchange Format (1987) */
     Gif89a, /**< Graphics Interchange Format (1989) */
@@ -46,7 +46,7 @@ enum class ContainerFormat
     Riff, /**< Resource Interchange File Format */
     RiffWave, /**< WAVE (subset of RIFF) */
     RiffAvi, /**< Audio Video Interleave (subset of RIFF) */
-    Tar, /** < Tar archive */
+    Tar, /**< Tar archive */
     TiffBigEndian, /**< Tagged Image File Format (big endian) */
     TiffLittleEndian, /**< Tagged Image File Format (little endian) */
     Utf16Text, /**< UTF-16 text */

tagvalue.cpp

@@ -456,7 +456,7 @@ u16string TagValue::toWString() const
  * \throws Throws ConversionException on failure.
  * \remarks Use this only, if UTF-16 text is assigned.
  */
-void TagValue::toWString(u16string &result) const
+void TagValue::toWString(std::u16string &result) const
 {
     if(!isEmpty()) {
         switch(m_type) {