Skip to content

Commit d466b72

Browse files
felipdsa21felipdsa21
authored
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.
1 parent c3a0e1d commit d466b72

7 files changed

Lines changed: 122 additions & 87 deletions

File tree

‎taglib/ape/apeitem.h‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -172,7 +172,7 @@ namespace TagLib {
172172
void setReadOnly(bool readOnly);
173173

174174
/*!
175-
* Return \c true if the item is read-only.
175+
* Returns \c true if the item is read-only.
176176
*/
177177
bool isReadOnly() const;
178178

‎taglib/flac/flacproperties.h‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@ namespace TagLib {
8787
int bitsPerSample() const;
8888

8989
/*!
90-
* Return the number of sample frames.
90+
* Returns the number of sample frames.
9191
*/
9292
unsigned long long sampleFrames() const;
9393

‎taglib/mp4/mp4atom.h‎

Lines changed: 42 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -35,27 +35,48 @@ namespace TagLib {
3535
namespace MP4 {
3636

3737
enum AtomDataType {
38-
TypeImplicit = 0, // for use with tags for which no type needs to be indicated because only one type is allowed
39-
TypeUTF8 = 1, // without any count or null terminator
40-
TypeUTF16 = 2, // also known as UTF-16BE
41-
TypeSJIS = 3, // deprecated unless it is needed for special Japanese characters
42-
TypeHTML = 6, // the HTML file header specifies which HTML version
43-
TypeXML = 7, // the XML header must identify the DTD or schemas
44-
TypeUUID = 8, // also known as GUID; stored as 16 bytes in binary (valid as an ID)
45-
TypeISRC = 9, // stored as UTF-8 text (valid as an ID)
46-
TypeMI3P = 10, // stored as UTF-8 text (valid as an ID)
47-
TypeGIF = 12, // (deprecated) a GIF image
48-
TypeJPEG = 13, // a JPEG image
49-
TypePNG = 14, // a PNG image
50-
TypeURL = 15, // absolute, in UTF-8 characters
51-
TypeDuration = 16, // in milliseconds, 32-bit integer
52-
TypeDateTime = 17, // in UTC, counting seconds since midnight, January 1, 1904; 32 or 64-bits
53-
TypeGenred = 18, // a list of enumerated values
54-
TypeInteger = 21, // a signed big-endian integer with length one of { 1,2,3,4,8 } bytes
55-
TypeRIAAPA = 24, // RIAA parental advisory; { -1=no, 1=yes, 0=unspecified }, 8-bit integer
56-
TypeUPC = 25, // Universal Product Code, in text UTF-8 format (valid as an ID)
57-
TypeBMP = 27, // Windows bitmap image
58-
TypeUndefined = 255 // undefined
38+
//! For use with tags for which no type needs to be indicated because only one type is allowed
39+
TypeImplicit = 0,
40+
//! Without any count or null terminator
41+
TypeUTF8 = 1,
42+
//! Also known as UTF-16BE
43+
TypeUTF16 = 2,
44+
//! Deprecated unless it is needed for special Japanese characters
45+
TypeSJIS = 3,
46+
//! The HTML file header specifies which HTML version
47+
TypeHTML = 6,
48+
//! The XML header must identify the DTD or schemas
49+
TypeXML = 7,
50+
//! Also known as GUID; stored as 16 bytes in binary (valid as an ID)
51+
TypeUUID = 8,
52+
//! Stored as UTF-8 text (valid as an ID)
53+
TypeISRC = 9,
54+
//! Stored as UTF-8 text (valid as an ID)
55+
TypeMI3P = 10,
56+
//! (Deprecated) A GIF image
57+
TypeGIF = 12,
58+
//! A JPEG image
59+
TypeJPEG = 13,
60+
//! A PNG image
61+
TypePNG = 14,
62+
//! Absolute, in UTF-8 characters
63+
TypeURL = 15,
64+
//! In milliseconds, 32-bit integer
65+
TypeDuration = 16,
66+
//! In UTC, counting seconds since midnight, January 1, 1904; 32 or 64-bits
67+
TypeDateTime = 17,
68+
//! A list of enumerated values
69+
TypeGenred = 18,
70+
//! A signed big-endian integer with length one of { 1,2,3,4,8 } bytes
71+
TypeInteger = 21,
72+
//! RIAA parental advisory; { -1=no, 1=yes, 0=unspecified }, 8-bit integer
73+
TypeRIAAPA = 24,
74+
//! Universal Product Code, in text UTF-8 format (valid as an ID)
75+
TypeUPC = 25,
76+
//! Windows bitmap image
77+
TypeBMP = 27,
78+
//! Undefined
79+
TypeUndefined = 255
5980
};
6081

6182
#ifndef DO_NOT_DOCUMENT

‎taglib/mpc/mpcproperties.h‎

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -93,28 +93,32 @@ namespace TagLib {
9393
unsigned long sampleFrames() const;
9494

9595
/*!
96-
* Returns the track gain as an integer value,
97-
* to convert to dB: trackGain in dB = 64.82 - (trackGain / 256)
96+
* Returns the track gain as an integer value.
97+
*
98+
* To convert to dB: trackGain in dB = 64.82 - (trackGain / 256)
9899
*/
99100
int trackGain() const;
100101

101102
/*!
102-
* Returns the track peak as an integer value,
103-
* to convert to dB: trackPeak in dB = trackPeak / 256
104-
* to convert to floating [-1..1]: trackPeak = 10^(trackPeak / 256 / 20)/32768
103+
* Returns the track peak as an integer value.
104+
*
105+
* To convert to dB: trackPeak in dB = trackPeak / 256 \n
106+
* To convert to floating [-1..1]: trackPeak = 10^(trackPeak / 256 / 20)/32768
105107
*/
106108
int trackPeak() const;
107109

108110
/*!
109-
* Returns the album gain as an integer value,
110-
* to convert to dB: albumGain in dB = 64.82 - (albumGain / 256)
111+
* Returns the album gain as an integer value.
112+
*
113+
* To convert to dB: albumGain in dB = 64.82 - (albumGain / 256)
111114
*/
112115
int albumGain() const;
113116

114117
/*!
115-
* Returns the album peak as an integer value,
116-
* to convert to dB: albumPeak in dB = albumPeak / 256
117-
* to convert to floating [-1..1]: albumPeak = 10^(albumPeak / 256 / 20)/32768
118+
* Returns the album peak as an integer value.
119+
*
120+
* To convert to dB: albumPeak in dB = albumPeak / 256 \n
121+
* To convert to floating [-1..1]: albumPeak = 10^(albumPeak / 256 / 20)/32768
118122
*/
119123
int albumPeak() const;
120124

‎taglib/mpeg/id3v2/frames/eventtimingcodesframe.h‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,9 @@ namespace TagLib {
5858
};
5959

6060
/*!
61-
* Event types defined in id3v2.4.0-frames.txt 4.5. Event timing codes.
61+
* Event types defined in
62+
* <a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-frames.txt">
63+
* id3v2.4.0-frames.txt</a> 4.5. Event timing codes.
6264
*/
6365
enum EventType {
6466
Padding = 0x00,

‎taglib/mpeg/id3v2/frames/textidentificationframe.h‎

Lines changed: 47 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -45,52 +45,53 @@ namespace TagLib {
4545
* identification frames. There are a number of variations on this. Those
4646
* enumerated in the ID3v2.4 standard are:
4747
*
48-
* <ul>
49-
* <li><b>TALB</b> Album/Movie/Show title</li>
50-
* <li><b>TBPM</b> BPM (beats per minute)</li>
51-
* <li><b>TCOM</b> Composer</li>
52-
* <li><b>TCON</b> Content type</li>
53-
* <li><b>TCOP</b> Copyright message</li>
54-
* <li><b>TDEN</b> Encoding time</li>
55-
* <li><b>TDLY</b> Playlist delay</li>
56-
* <li><b>TDOR</b> Original release time</li>
57-
* <li><b>TDRC</b> Recording time</li>
58-
* <li><b>TDRL</b> Release time</li>
59-
* <li><b>TDTG</b> Tagging time</li>
60-
* <li><b>TENC</b> Encoded by</li>
61-
* <li><b>TEXT</b> Lyricist/Text writer</li>
62-
* <li><b>TFLT</b> %File type</li>
63-
* <li><b>TIPL</b> Involved people list</li>
64-
* <li><b>TIT1</b> Content group description</li>
65-
* <li><b>TIT2</b> Title/songname/content description</li>
66-
* <li><b>TIT3</b> Subtitle/Description refinement</li>
67-
* <li><b>TKEY</b> Initial key</li>
68-
* <li><b>TLAN</b> Language(s)</li>
69-
* <li><b>TLEN</b> Length</li>
70-
* <li><b>TMCL</b> Musician credits list</li>
71-
* <li><b>TMED</b> Media type</li>
72-
* <li><b>TMOO</b> Mood</li>
73-
* <li><b>TOAL</b> Original album/movie/show title</li>
74-
* <li><b>TOFN</b> Original filename</li>
75-
* <li><b>TOLY</b> Original lyricist(s)/text writer(s)</li>
76-
* <li><b>TOPE</b> Original artist(s)/performer(s)</li>
77-
* <li><b>TOWN</b> %File owner/licensee</li>
78-
* <li><b>TPE1</b> Lead performer(s)/Soloist(s)</li>
79-
* <li><b>TPE2</b> Band/orchestra/accompaniment</li>
80-
* <li><b>TPE3</b> Conductor/performer refinement</li>
81-
* <li><b>TPE4</b> Interpreted, remixed, or otherwise modified by</li>
82-
* <li><b>TPOS</b> Part of a set</li>
83-
* <li><b>TPRO</b> Produced notice</li>
84-
* <li><b>TPUB</b> Publisher</li>
85-
* <li><b>TRCK</b> Track number/Position in set</li>
86-
* <li><b>TRSN</b> Internet radio station name</li>
87-
* <li><b>TRSO</b> Internet radio station owner</li>
88-
* <li><b>TSOA</b> Album sort order</li>
89-
* <li><b>TSOP</b> Performer sort order</li>
90-
* <li><b>TSOT</b> Title sort order</li>
91-
* <li><b>TSRC</b> ISRC (international standard recording code)</li>
92-
* <li><b>TSSE</b> Software/Hardware and settings used for encoding</li>
93-
* <li><b>TSST</b> Set subtitle</li>
48+
* %Frame | Description
49+
* :----: | :-----------------------------------------------
50+
* TALB | Album/Movie/Show title
51+
* TBPM | BPM (beats per minute)
52+
* TCOM | Composer
53+
* TCON | Content type
54+
* TCOP | Copyright message
55+
* TDEN | Encoding time
56+
* TDLY | Playlist delay
57+
* TDOR | Original release time
58+
* TDRC | Recording time
59+
* TDRL | Release time
60+
* TDTG | Tagging time
61+
* TENC | Encoded by
62+
* TEXT | Lyricist/Text writer
63+
* TFLT | %File type
64+
* TIPL | Involved people list
65+
* TIT1 | Content group description
66+
* TIT2 | Title/songname/content description
67+
* TIT3 | Subtitle/Description refinement
68+
* TKEY | Initial key
69+
* TLAN | Language(s)
70+
* TLEN | Length
71+
* TMCL | Musician credits list
72+
* TMED | Media type
73+
* TMOO | Mood
74+
* TOAL | Original album/movie/show title
75+
* TOFN | Original filename
76+
* TOLY | Original lyricist(s)/text writer(s)
77+
* TOPE | Original artist(s)/performer(s)
78+
* TOWN | %File owner/licensee
79+
* TPE1 | Lead performer(s)/Soloist(s)
80+
* TPE2 | Band/orchestra/accompaniment
81+
* TPE3 | Conductor/performer refinement
82+
* TPE4 | Interpreted, remixed, or otherwise modified by
83+
* TPOS | Part of a set
84+
* TPRO | Produced notice
85+
* TPUB | Publisher
86+
* TRCK | Track number/Position in set
87+
* TRSN | Internet radio station name
88+
* TRSO | Internet radio station owner
89+
* TSOA | Album sort order
90+
* TSOP | Performer sort order
91+
* TSOT | Title sort order
92+
* TSRC | ISRC (international standard recording code)
93+
* TSSE | Software/Hardware and settings used for encoding
94+
* TSST | Set subtitle
9495
* </ul>
9596
*
9697
* The ID3v2 Frames document gives a description of each of these formats

‎taglib/shorten/shortenproperties.h‎

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -52,13 +52,20 @@ namespace TagLib {
5252

5353
//! Returns the Shorten file version (1-3).
5454
int shortenVersion() const;
55-
//! Returns the file type (0-9).
56-
//! 0 = 8-bit µ-law,
57-
//! 1 = signed 8-bit PCM, 2 = unsigned 8-bit PCM,
58-
//! 3 = signed big-endian 16-bit PCM, 4 = unsigned big-endian 16-bit PCM,
59-
//! 5 = signed little-endian 16-bit PCM, 6 = unsigned little-endian 16-bit PCM,
60-
//! 7 = 8-bit ITU-T G.711 µ-law, 8 = 8-bit µ-law,
61-
//! 9 = 8-bit A-law, 10 = 8-bit ITU-T G.711 A-law
55+
//! Returns the file type (0-10).
56+
//! Value | %File type
57+
//! :---: | :--------------------------------
58+
//! 0 | 8-bit µ-law
59+
//! 1 | signed 8-bit PCM
60+
//! 2 | unsigned 8-bit PCM
61+
//! 3 | signed big-endian 16-bit PCM
62+
//! 4 | unsigned big-endian 16-bit PCM
63+
//! 5 | signed little-endian 16-bit PCM
64+
//! 6 | unsigned little-endian 16-bit PCM
65+
//! 7 | 8-bit ITU-T G.711 µ-law
66+
//! 8 | 8-bit µ-law
67+
//! 9 | 8-bit A-law
68+
//! 10 | 8-bit ITU-T G.711 A-law
6269
int fileType() const;
6370
int bitsPerSample() const;
6471
unsigned long sampleFrames() const;

0 commit comments

Comments
 (0)