mirror/taglib
1
0
Fork 0
mirror of https://github.com/taglib/taglib.git synced 2026-05-25 13:08:55 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs: Some improvements to the documentation (#1337)

Browse Source 
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.
This commit is contained in:
Felipe
2026-04-13 15:05:53 -03:00
committed by GitHub
parent c3a0e1d0a2
commit d466b72eea
7 changed files with 122 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
taglib/ape/apeitem.h
View File

@@ -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;

2
taglib/flac/flacproperties.h
View File

@@ -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;

63
taglib/mp4/mp4atom.h
View File

@@ -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

24
taglib/mpc/mpcproperties.h
View File

@@ -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;

4
taglib/mpeg/id3v2/frames/eventtimingcodesframe.h
View File

@@ -58,7 +58,9 @@ namespace TagLib {
};
/*!
* Event types defined in id3v2.4.0-frames.txt 4.5. Event timing codes.
* Event types defined in
* <a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-frames.txt">
* id3v2.4.0-frames.txt</a> 4.5. Event timing codes.
*/
enum EventType {
Padding = 0x00,

93
taglib/mpeg/id3v2/frames/textidentificationframe.h
View File

@@ -45,52 +45,53 @@ namespace TagLib {
* identification frames. There are a number of variations on this. Those
* enumerated in the ID3v2.4 standard are:
*
* <ul>
* <li><b>TALB</b> Album/Movie/Show title</li>
* <li><b>TBPM</b> BPM (beats per minute)</li>
* <li><b>TCOM</b> Composer</li>
* <li><b>TCON</b> Content type</li>
* <li><b>TCOP</b> Copyright message</li>
* <li><b>TDEN</b> Encoding time</li>
* <li><b>TDLY</b> Playlist delay</li>
* <li><b>TDOR</b> Original release time</li>
* <li><b>TDRC</b> Recording time</li>
* <li><b>TDRL</b> Release time</li>
* <li><b>TDTG</b> Tagging time</li>
* <li><b>TENC</b> Encoded by</li>
* <li><b>TEXT</b> Lyricist/Text writer</li>
* <li><b>TFLT</b> %File type</li>
* <li><b>TIPL</b> Involved people list</li>
* <li><b>TIT1</b> Content group description</li>
* <li><b>TIT2</b> Title/songname/content description</li>
* <li><b>TIT3</b> Subtitle/Description refinement</li>
* <li><b>TKEY</b> Initial key</li>
* <li><b>TLAN</b> Language(s)</li>
* <li><b>TLEN</b> Length</li>
* <li><b>TMCL</b> Musician credits list</li>
* <li><b>TMED</b> Media type</li>
* <li><b>TMOO</b> Mood</li>
* <li><b>TOAL</b> Original album/movie/show title</li>
* <li><b>TOFN</b> Original filename</li>
* <li><b>TOLY</b> Original lyricist(s)/text writer(s)</li>
* <li><b>TOPE</b> Original artist(s)/performer(s)</li>
* <li><b>TOWN</b> %File owner/licensee</li>
* <li><b>TPE1</b> Lead performer(s)/Soloist(s)</li>
* <li><b>TPE2</b> Band/orchestra/accompaniment</li>
* <li><b>TPE3</b> Conductor/performer refinement</li>
* <li><b>TPE4</b> Interpreted, remixed, or otherwise modified by</li>
* <li><b>TPOS</b> Part of a set</li>
* <li><b>TPRO</b> Produced notice</li>
* <li><b>TPUB</b> Publisher</li>
* <li><b>TRCK</b> Track number/Position in set</li>
* <li><b>TRSN</b> Internet radio station name</li>
* <li><b>TRSO</b> Internet radio station owner</li>
* <li><b>TSOA</b> Album sort order</li>
* <li><b>TSOP</b> Performer sort order</li>
* <li><b>TSOT</b> Title sort order</li>
* <li><b>TSRC</b> ISRC (international standard recording code)</li>
* <li><b>TSSE</b> Software/Hardware and settings used for encoding</li>
* <li><b>TSST</b> Set subtitle</li>
* %Frame | Description
* :----: | :-----------------------------------------------
* TALB | Album/Movie/Show title
* TBPM | BPM (beats per minute)
* TCOM | Composer
* TCON | Content type
* TCOP | Copyright message
* TDEN | Encoding time
* TDLY | Playlist delay
* TDOR | Original release time
* TDRC | Recording time
* TDRL | Release time
* TDTG | Tagging time
* TENC | Encoded by
* TEXT | Lyricist/Text writer
* TFLT | %File type
* TIPL | Involved people list
* TIT1 | Content group description
* TIT2 | Title/songname/content description
* TIT3 | Subtitle/Description refinement
* TKEY | Initial key
* TLAN | Language(s)
* TLEN | Length
* TMCL | Musician credits list
* TMED | Media type
* TMOO | Mood
* TOAL | Original album/movie/show title
* TOFN | Original filename
* TOLY | Original lyricist(s)/text writer(s)
* TOPE | Original artist(s)/performer(s)
* TOWN | %File owner/licensee
* TPE1 | Lead performer(s)/Soloist(s)
* TPE2 | Band/orchestra/accompaniment
* TPE3 | Conductor/performer refinement
* TPE4 | Interpreted, remixed, or otherwise modified by
* TPOS | Part of a set
* TPRO | Produced notice
* TPUB | Publisher
* TRCK | Track number/Position in set
* TRSN | Internet radio station name
* TRSO | Internet radio station owner
* TSOA | Album sort order
* TSOP | Performer sort order
* TSOT | Title sort order
* TSRC | ISRC (international standard recording code)
* TSSE | Software/Hardware and settings used for encoding
* TSST | Set subtitle
* </ul>
*
* The ID3v2 Frames document gives a description of each of these formats

21
taglib/shorten/shortenproperties.h
View File

@@ -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;