From d466b72eeafa6bdfa3d59bba4d8b0a2d0947cbed Mon Sep 17 00:00:00 2001 From: Felipe <93343201+felipdsa21@users.noreply.github.com> Date: Mon, 13 Apr 2026 15:05:53 -0300 Subject: [PATCH] docs: Some improvements to the documentation (#1337) Make MP4 AtomDataType descriptions visible in the generated documentation. Convert the ID3v2 text frame listing into a table. Convert the shorten `fileType()` documentation into a table. Fix some typos. Add link to specification in `EventType` for consistency with other headers. --- taglib/ape/apeitem.h | 2 +- taglib/flac/flacproperties.h | 2 +- taglib/mp4/mp4atom.h | 63 ++++++++----- taglib/mpc/mpcproperties.h | 24 +++-- .../mpeg/id3v2/frames/eventtimingcodesframe.h | 4 +- .../id3v2/frames/textidentificationframe.h | 93 ++++++++++--------- taglib/shorten/shortenproperties.h | 21 +++-- 7 files changed, 122 insertions(+), 87 deletions(-) diff --git a/taglib/ape/apeitem.h b/taglib/ape/apeitem.h index af75704c..cf00581c 100644 --- a/taglib/ape/apeitem.h +++ b/taglib/ape/apeitem.h @@ -172,7 +172,7 @@ namespace TagLib { void setReadOnly(bool readOnly); /*! - * Return \c true if the item is read-only. + * Returns \c true if the item is read-only. */ bool isReadOnly() const; diff --git a/taglib/flac/flacproperties.h b/taglib/flac/flacproperties.h index 5926a82d..3e8aef0b 100644 --- a/taglib/flac/flacproperties.h +++ b/taglib/flac/flacproperties.h @@ -87,7 +87,7 @@ namespace TagLib { int bitsPerSample() const; /*! - * Return the number of sample frames. + * Returns the number of sample frames. */ unsigned long long sampleFrames() const; diff --git a/taglib/mp4/mp4atom.h b/taglib/mp4/mp4atom.h index 1776ba90..7ecd6f00 100644 --- a/taglib/mp4/mp4atom.h +++ b/taglib/mp4/mp4atom.h @@ -35,27 +35,48 @@ namespace TagLib { namespace MP4 { enum AtomDataType { - TypeImplicit = 0, // for use with tags for which no type needs to be indicated because only one type is allowed - TypeUTF8 = 1, // without any count or null terminator - TypeUTF16 = 2, // also known as UTF-16BE - TypeSJIS = 3, // deprecated unless it is needed for special Japanese characters - TypeHTML = 6, // the HTML file header specifies which HTML version - TypeXML = 7, // the XML header must identify the DTD or schemas - TypeUUID = 8, // also known as GUID; stored as 16 bytes in binary (valid as an ID) - TypeISRC = 9, // stored as UTF-8 text (valid as an ID) - TypeMI3P = 10, // stored as UTF-8 text (valid as an ID) - TypeGIF = 12, // (deprecated) a GIF image - TypeJPEG = 13, // a JPEG image - TypePNG = 14, // a PNG image - TypeURL = 15, // absolute, in UTF-8 characters - TypeDuration = 16, // in milliseconds, 32-bit integer - TypeDateTime = 17, // in UTC, counting seconds since midnight, January 1, 1904; 32 or 64-bits - TypeGenred = 18, // a list of enumerated values - TypeInteger = 21, // a signed big-endian integer with length one of { 1,2,3,4,8 } bytes - TypeRIAAPA = 24, // RIAA parental advisory; { -1=no, 1=yes, 0=unspecified }, 8-bit integer - TypeUPC = 25, // Universal Product Code, in text UTF-8 format (valid as an ID) - TypeBMP = 27, // Windows bitmap image - TypeUndefined = 255 // undefined + //! For use with tags for which no type needs to be indicated because only one type is allowed + TypeImplicit = 0, + //! Without any count or null terminator + TypeUTF8 = 1, + //! Also known as UTF-16BE + TypeUTF16 = 2, + //! Deprecated unless it is needed for special Japanese characters + TypeSJIS = 3, + //! The HTML file header specifies which HTML version + TypeHTML = 6, + //! The XML header must identify the DTD or schemas + TypeXML = 7, + //! Also known as GUID; stored as 16 bytes in binary (valid as an ID) + TypeUUID = 8, + //! Stored as UTF-8 text (valid as an ID) + TypeISRC = 9, + //! Stored as UTF-8 text (valid as an ID) + TypeMI3P = 10, + //! (Deprecated) A GIF image + TypeGIF = 12, + //! A JPEG image + TypeJPEG = 13, + //! A PNG image + TypePNG = 14, + //! Absolute, in UTF-8 characters + TypeURL = 15, + //! In milliseconds, 32-bit integer + TypeDuration = 16, + //! In UTC, counting seconds since midnight, January 1, 1904; 32 or 64-bits + TypeDateTime = 17, + //! A list of enumerated values + TypeGenred = 18, + //! A signed big-endian integer with length one of { 1,2,3,4,8 } bytes + TypeInteger = 21, + //! RIAA parental advisory; { -1=no, 1=yes, 0=unspecified }, 8-bit integer + TypeRIAAPA = 24, + //! Universal Product Code, in text UTF-8 format (valid as an ID) + TypeUPC = 25, + //! Windows bitmap image + TypeBMP = 27, + //! Undefined + TypeUndefined = 255 }; #ifndef DO_NOT_DOCUMENT diff --git a/taglib/mpc/mpcproperties.h b/taglib/mpc/mpcproperties.h index ca343da0..1e601467 100644 --- a/taglib/mpc/mpcproperties.h +++ b/taglib/mpc/mpcproperties.h @@ -93,28 +93,32 @@ namespace TagLib { unsigned long sampleFrames() const; /*! - * Returns the track gain as an integer value, - * to convert to dB: trackGain in dB = 64.82 - (trackGain / 256) + * Returns the track gain as an integer value. + * + * To convert to dB: trackGain in dB = 64.82 - (trackGain / 256) */ int trackGain() const; /*! - * Returns the track peak as an integer value, - * to convert to dB: trackPeak in dB = trackPeak / 256 - * to convert to floating [-1..1]: trackPeak = 10^(trackPeak / 256 / 20)/32768 + * Returns the track peak as an integer value. + * + * To convert to dB: trackPeak in dB = trackPeak / 256 \n + * To convert to floating [-1..1]: trackPeak = 10^(trackPeak / 256 / 20)/32768 */ int trackPeak() const; /*! - * Returns the album gain as an integer value, - * to convert to dB: albumGain in dB = 64.82 - (albumGain / 256) + * Returns the album gain as an integer value. + * + * To convert to dB: albumGain in dB = 64.82 - (albumGain / 256) */ int albumGain() const; /*! - * Returns the album peak as an integer value, - * to convert to dB: albumPeak in dB = albumPeak / 256 - * to convert to floating [-1..1]: albumPeak = 10^(albumPeak / 256 / 20)/32768 + * Returns the album peak as an integer value. + * + * To convert to dB: albumPeak in dB = albumPeak / 256 \n + * To convert to floating [-1..1]: albumPeak = 10^(albumPeak / 256 / 20)/32768 */ int albumPeak() const; diff --git a/taglib/mpeg/id3v2/frames/eventtimingcodesframe.h b/taglib/mpeg/id3v2/frames/eventtimingcodesframe.h index 2e6678a3..9771ea52 100644 --- a/taglib/mpeg/id3v2/frames/eventtimingcodesframe.h +++ b/taglib/mpeg/id3v2/frames/eventtimingcodesframe.h @@ -58,7 +58,9 @@ namespace TagLib { }; /*! - * Event types defined in id3v2.4.0-frames.txt 4.5. Event timing codes. + * Event types defined in + * + * id3v2.4.0-frames.txt 4.5. Event timing codes. */ enum EventType { Padding = 0x00, diff --git a/taglib/mpeg/id3v2/frames/textidentificationframe.h b/taglib/mpeg/id3v2/frames/textidentificationframe.h index c88e16ff..e7f2c587 100644 --- a/taglib/mpeg/id3v2/frames/textidentificationframe.h +++ b/taglib/mpeg/id3v2/frames/textidentificationframe.h @@ -45,52 +45,53 @@ namespace TagLib { * identification frames. There are a number of variations on this. Those * enumerated in the ID3v2.4 standard are: * - * * * The ID3v2 Frames document gives a description of each of these formats diff --git a/taglib/shorten/shortenproperties.h b/taglib/shorten/shortenproperties.h index b6a389c7..f8d51778 100644 --- a/taglib/shorten/shortenproperties.h +++ b/taglib/shorten/shortenproperties.h @@ -52,13 +52,20 @@ namespace TagLib { //! Returns the Shorten file version (1-3). int shortenVersion() const; - //! Returns the file type (0-9). - //! 0 = 8-bit µ-law, - //! 1 = signed 8-bit PCM, 2 = unsigned 8-bit PCM, - //! 3 = signed big-endian 16-bit PCM, 4 = unsigned big-endian 16-bit PCM, - //! 5 = signed little-endian 16-bit PCM, 6 = unsigned little-endian 16-bit PCM, - //! 7 = 8-bit ITU-T G.711 µ-law, 8 = 8-bit µ-law, - //! 9 = 8-bit A-law, 10 = 8-bit ITU-T G.711 A-law + //! Returns the file type (0-10). + //! Value | %File type + //! :---: | :-------------------------------- + //! 0 | 8-bit µ-law + //! 1 | signed 8-bit PCM + //! 2 | unsigned 8-bit PCM + //! 3 | signed big-endian 16-bit PCM + //! 4 | unsigned big-endian 16-bit PCM + //! 5 | signed little-endian 16-bit PCM + //! 6 | unsigned little-endian 16-bit PCM + //! 7 | 8-bit ITU-T G.711 µ-law + //! 8 | 8-bit µ-law + //! 9 | 8-bit A-law + //! 10 | 8-bit ITU-T G.711 A-law int fileType() const; int bitsPerSample() const; unsigned long sampleFrames() const;