Improve API doc

This commit is contained in:
Martchus 2016-06-10 23:08:01 +02:00
parent f06b64bd99
commit 2c5d463a9f
16 changed files with 53 additions and 43 deletions

View File

@ -149,19 +149,23 @@ set(TEST_SRC_FILES
tests/overall.cpp tests/overall.cpp
) )
set(DOC_FILES
README.md
)
# meta data # meta data
set(META_PROJECT_NAME tagparser) set(META_PROJECT_NAME tagparser)
set(META_PROJECT_VARNAME TAG_PARSER) set(META_PROJECT_VARNAME TAG_PARSER)
set(META_APP_NAME "Tag Parser") set(META_APP_NAME "Tag Parser")
set(META_APP_AUTHOR "Martchus") set(META_APP_AUTHOR "Martchus")
set(META_APP_URL "https://github.com/${META_APP_AUTHOR}/${META_PROJECT_NAME}") 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_MAJOR 6)
set(META_VERSION_MINOR 0) set(META_VERSION_MINOR 0)
set(META_VERSION_PATCH 0) set(META_VERSION_PATCH 0)
# find c++utilities # find c++utilities
find_package(c++utilities 3.3.0 REQUIRED) find_package(c++utilities 4.0.0 REQUIRED)
use_cpp_utilities() use_cpp_utilities()
# find zlib # find zlib
@ -174,3 +178,4 @@ include(BasicConfig)
include(WindowsResources) include(WindowsResources)
include(LibraryTarget) include(LibraryTarget)
include(TestTarget) include(TestTarget)
include(Doxygen)

View File

@ -39,7 +39,7 @@ API provides a way to check which encoding is present (when reading) and which e
can be used (when writing). can be used (when writing).
## Usage ## 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 ## Bugs, stability
- Matroska files composed of more than one segment aren't tested yet and might not work. - Matroska files composed of more than one segment aren't tested yet and might not work.

View File

@ -37,7 +37,7 @@ StreamDataBlock::StreamDataBlock() :
* *
* The object does NOT take ownership over the stream returned by the specified function. * 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) m_stream(stream)
{ {
auto &s = stream(); auto &s = stream();

View File

@ -75,7 +75,7 @@ AbstractTrack::AbstractTrack(istream &inputStream, ostream &outputStream, uint64
* information. * information.
* \param startOffset The start offset of the track in the specified \a stream. * \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) AbstractTrack(stream, stream, startOffset)
{} {}

View File

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

View File

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

View File

@ -40,14 +40,13 @@ bool Id3v1Tag::canEncodingBeUsed(TagTextEncoding encoding) const
/*! /*!
* \brief Parses tag information from the specified \a stream. * \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. * \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 std::ios_base::failure when an IO error occurs.
* \throws Throws Media::Failure or a derived exception when a parsing * \throws Throws Media::Failure or a derived exception when a parsing
* error occurs. * error occurs.
*/ */
void Id3v1Tag::parse(istream &stream, bool autoSeek) void Id3v1Tag::parse(std::istream &stream, bool autoSeek)
{ {
invalidateStatus(); invalidateStatus();
static const string context("parsing ID3v1 tag"); 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 * \throws Throws Media::Failure or a derived exception when a parsing
* error occurs. * error occurs.
*/ */
void Id3v1Tag::parse(iostream &stream) void Id3v1Tag::parse(std::iostream &stream)
{ {
return parse(stream, false); return parse(stream, false);
} }

View File

@ -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 * \remarks The length is always returned as the number of bytes, not as the number of characters (makes a difference for
* UTF-16 encodings). * 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); tuple<const char *, size_t, const char *> res(buffer, 0, buffer + bufferSize);
switch(encoding) { 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 tagValue Specifies the tag value used to store the results.
* \param typeInfo Specifies a byte used to store the type info. * \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"); static const string context("parsing ID3v2.2 picture frame");
if(maxSize < 6) { 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 tagValue Specifies the tag value used to store the results.
* \param typeInfo Specifies a byte used to store the type info. * \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"); static const string context("parsing ID3v2.3 picture frame");
const char *end = buffer + maxSize; 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 dataSize Specifies the maximal number of bytes to read from the buffer.
* \param tagValue Specifies the tag value used to store the results. * \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"); static const string context("parsing comment/unsynchronized lyrics frame");
const char *end = buffer + dataSize; 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 value Specifies the string to make.
* \param encoding Specifies the encoding of 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()); 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. * \brief Writes an encoding denoation and the specified \a data to a \a buffer.
* \param buffer Specifies the buffer. * \param buffer Specifies the buffer.
* \param bufferSize Specifies the size of \a buffer.
* \param encoding Specifies the data encoding. * \param encoding Specifies the data encoding.
* \param data Specifies the data. * \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 // calculate buffer size
if(!data) { if(!data) {

View File

@ -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::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::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); 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 parseLegacyPicture(const char *buffer, std::size_t maxSize, TagValue &tagValue, byte &typeInfo);
void parsePicture(const char *buffer, 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, size_t maxSize, TagValue &tagValue); void parseComment(const char *buffer, std::size_t maxSize, TagValue &tagValue);
void parseBom(const char *buffer, std::size_t maxSize, TagTextEncoding &encoding); void parseBom(const char *buffer, std::size_t maxSize, TagTextEncoding &encoding);
// making helper // making helper
byte makeTextEncodingByte(TagTextEncoding textEncoding); byte makeTextEncodingByte(TagTextEncoding textEncoding);
void makeString(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, const std::string &value, TagTextEncoding encoding); 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 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 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); void makeComment(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, const TagValue &comment);

View File

@ -427,6 +427,8 @@ byte EbmlElement::makeUInteger(uint64 value, char *buff)
/*! /*!
* \brief Writes \a value to \a buff. * \brief Writes \a value to \a buff.
* \returns Returns the number of bytes written 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. * \param minBytes Specifies the minimum number of bytes to use.
*/ */
byte EbmlElement::makeUInteger(uint64 value, char *buff, byte minBytes) 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 id Specifies the element ID.
* \param content Specifies the value of the element as string. * \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]; char buff1[8];
byte sizeLength = EbmlElement::makeId(id, buff1); byte sizeLength = EbmlElement::makeId(id, buff1);

View File

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

View File

@ -95,7 +95,6 @@ void MatroskaSeekInfo::parse(EbmlElement *seekHeadElement)
/*! /*!
* \brief Writes a "SeekHead" element for the current instance to the specified \a stream. * \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 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 ios_base::failure when an IO error occurs.
* \throws Throws Failure or a derived exception when a making error occurs. * \throws Throws Failure or a derived exception when a making error occurs.
*/ */

View File

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

View File

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

View File

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

View File

@ -456,7 +456,7 @@ u16string TagValue::toWString() const
* \throws Throws ConversionException on failure. * \throws Throws ConversionException on failure.
* \remarks Use this only, if UTF-16 text is assigned. * \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()) { if(!isEmpty()) {
switch(m_type) { switch(m_type) {