Skip to content

Commit c9d79d5

Browse files
MrCSharp22MrCSharp22
committed
Added documentation for publicly visible methods/properties and small refactoring
1 parent b0bb25f commit c9d79d5

File tree

5 files changed

+352
-60
lines changed

5 files changed

+352
-60
lines changed

‎src/TagLib/Id3v2/EventType.cs

+79
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,134 @@
11
namespace TagLib.Id3v2
22
{
3+
/// <summary>
4+
/// Specifies the event type used by a <see
5+
/// cref="EventTimeCode" /> and <see cref="EventTimeCodesFrame"/>.
6+
/// </summary>
37
public enum EventType
48
{
9+
/// <summary>
10+
/// The padding - no meaning
11+
/// </summary>
512
Padding = 0x00,
613

14+
/// <summary>
15+
/// The end of initial silence
16+
/// </summary>
717
EndOfInitialSilence = 0x01,
818

19+
/// <summary>
20+
/// The intro start
21+
/// </summary>
922
IntroStart = 0x02,
1023

24+
/// <summary>
25+
/// The main part start
26+
/// </summary>
1127
MainPartStart = 0x03,
1228

29+
/// <summary>
30+
/// The outro start
31+
/// </summary>
1332
OutroStart = 0x04,
1433

34+
/// <summary>
35+
/// The outro end
36+
/// </summary>
1537
OutroEnd = 0x05,
1638

39+
/// <summary>
40+
/// The verse start
41+
/// </summary>
1742
VerseStart = 0x06,
1843

44+
/// <summary>
45+
/// The refrain start
46+
/// </summary>
1947
RefrainStart = 0x07,
2048

49+
/// <summary>
50+
/// The interlude start
51+
/// </summary>
2152
InterludeStart = 0x08,
2253

54+
/// <summary>
55+
/// The theme start
56+
/// </summary>
2357
ThemeStart = 0x09,
2458

59+
/// <summary>
60+
/// The variation start
61+
/// </summary>
2562
VariationStart = 0x0A,
2663

64+
/// <summary>
65+
/// The key change
66+
/// </summary>
2767
KeyChange = 0x0B,
2868

69+
/// <summary>
70+
/// The time change
71+
/// </summary>
2972
TimeChange = 0x0C,
3073

74+
/// <summary>
75+
/// momentary unwanted noise (Snap, Crackle & Pop)
76+
/// </summary>
3177
MomentaryUnwantedNoise = 0x0D,
3278

79+
/// <summary>
80+
/// The sustained noise
81+
/// </summary>
3382
SustainedNoise = 0x0E,
3483

84+
/// <summary>
85+
/// The sustained noise end
86+
/// </summary>
3587
SustainedNoiseEnd = 0x0F,
3688

89+
/// <summary>
90+
/// The intro end
91+
/// </summary>
3792
IntroEnd = 0x10,
3893

94+
/// <summary>
95+
/// The main part end
96+
/// </summary>
3997
MainPartEnd = 0x11,
4098

99+
/// <summary>
100+
/// The verse end
101+
/// </summary>
41102
VerseEnd = 0x12,
42103

104+
/// <summary>
105+
/// The refrain end
106+
/// </summary>
43107
RefrainEnd = 0x13,
44108

109+
/// <summary>
110+
/// The theme end
111+
/// </summary>
45112
ThemeEnd = 0x14,
46113

114+
/// <summary>
115+
/// Profanity starts
116+
/// </summary>
47117
Profanity = 0x15,
48118

119+
/// <summary>
120+
/// The profanity end
121+
/// </summary>
49122
ProfanityEnd = 0x16,
50123

124+
/// <summary>
125+
/// The audio end
126+
/// </summary>
51127
AudioEnd = 0xFD,
52128

129+
/// <summary>
130+
/// The audio file end
131+
/// </summary>
53132
AudioFileEnd = 0xFE,
54133
}
55134
}

‎src/TagLib/Id3v2/Frames/EventTimeCodesFrame.cs

+192
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,99 @@
22

33
namespace TagLib.Id3v2
44
{
5+
/// <summary>
6+
/// This class extends <see cref="Frame" />, implementing support for
7+
/// ID3v2 Event Time Codes (ETCO) Frames.
8+
/// </summary>
9+
/// <remarks>
10+
/// Event time codes Frames should contain a list of events occurring
11+
/// throughout the track such as the start of the main part and the end of it.
12+
/// To see all available event types see <see cref="EventType"/>.
13+
/// </remarks>
14+
/// <example>
15+
/// <para>Reading the Event Time Codes from a tag.</para>
16+
/// <code lang="C#">
17+
/// using TagLib;
18+
/// using TagLib.Id3v2;
19+
///
20+
/// public static class LookupUtil
21+
/// {
22+
/// public static ByteVector GetTrackEvents(string filename)
23+
/// {
24+
/// File file = File.Create (filename, ReadStyle.None);
25+
/// Id3v2.Tag tag = file.GetTag (TagTypes.Id3v2, false) as Id3v2.Tag;
26+
/// if (tag == null)
27+
/// return new ByteVector ();
28+
///
29+
/// EventTimeCodesFrame frame = EventTimeCodesFrame.Get (tag, false);
30+
/// if (frame == null)
31+
/// return new ByteVector ();
32+
///
33+
/// return frame.Data;
34+
/// }
35+
/// }
36+
/// </code>
37+
/// <code lang="C++">
38+
/// #using &lt;System.dll>
39+
/// #using &lt;taglib-sharp.dll>
40+
///
41+
/// using System;
42+
/// using TagLib;
43+
/// using TagLib::Id3v2;
44+
///
45+
/// public ref class LookupUtil abstract sealed
46+
/// {
47+
/// public:
48+
/// static ByteVector^ GetTrackEvents (String^ filename)
49+
/// {
50+
/// File^ file = File::Create (filename, ReadStyle::None);
51+
/// Id3v2::Tag^ tag = dynamic_cast&lt;Id3v2::Tag^> (file.GetTag (TagTypes::Id3v2, false));
52+
/// if (tag == null)
53+
/// return gcnew ByteVector;
54+
///
55+
/// EventTimeCodesFrame^ frame = EventTimeCodesFrame::Get (tag, false);
56+
/// if (frame == null)
57+
/// return gcnew ByteVector;
58+
///
59+
/// return frame->Data;
60+
/// }
61+
/// }
62+
/// </code>
63+
/// <code lang="VB">
64+
/// Imports TagLib
65+
/// Imports TagLib.Id3v2
66+
///
67+
/// Public Shared Class LookupUtil
68+
/// Public Shared Sub GetTrackEvents (filename As String) As TagLib.ByteVector
69+
/// Dim file As File = File.Create (filename, ReadStyle.None)
70+
/// Dim tag As Id3v2.Tag = file.GetTag (TagTypes.Id3v2, False)
71+
/// If tag Is Nothing Return New ByteVector ()
72+
///
73+
/// Dim frame As EventTimeCodesFrame = EventTimeCodesFrame.Get (tag, False)
74+
/// If frame Is Nothing Return New ByteVector ()
75+
///
76+
/// Return frame.Data
77+
/// End Sub
78+
/// End Class
79+
/// </code>
80+
/// <code lang="Boo">
81+
/// import TagLib
82+
/// import TagLib.Id3v2
83+
///
84+
/// public static class LookupUtil:
85+
/// static def GetTrackEvents (filename as string) as TagLib.ByteVector:
86+
/// file as File = File.Create (filename, ReadStyle.None)
87+
/// tag as Id3v2.Tag = file.GetTag (TagTypes.Id3v2, false)
88+
/// if tag == null:
89+
/// return ByteVector ()
90+
///
91+
/// frame as EventTimeCodesFrame = EventTimeCodesFrame.Get (tag, false)
92+
/// if frame == null:
93+
/// return ByteVector ()
94+
///
95+
/// return frame.Data
96+
/// </code>
97+
/// </example>
598
public class EventTimeCodesFrame : Frame
699
{
7100
#region Private Properties
@@ -14,28 +107,90 @@ public class EventTimeCodesFrame : Frame
14107

15108
#region Constructors
16109

110+
/// <summary>
111+
/// Constructs and initializes a new instance of <see
112+
/// cref="EventTimeCodesFrame" /> with empty
113+
/// identifier data.
114+
/// </summary>
115+
/// <remarks>
116+
/// When a frame is created, it is not automatically added to
117+
/// the tag. Consider using <see cref="Get" /> for more
118+
/// integrated frame creation.
119+
/// </remarks>
17120
public EventTimeCodesFrame() : base (FrameType.ETCO, 4)
18121
{
19122
Flags = FrameFlags.FileAlterPreservation;
20123
}
21124

125+
/// <summary>
126+
/// Constructs and initializes a new instance of <see
127+
/// cref="EventTimeCodesFrame" /> by reading its raw data
128+
/// in a specified ID3v2 version.
129+
/// </summary>
130+
/// <param name="timestampFormat">
131+
/// A <see cref="TimestampFormat" /> Specifies the time unit to use in this frame.
132+
/// </param>
22133
public EventTimeCodesFrame(TimestampFormat timestampFormat) : base(FrameType.ETCO, 4)
23134
{
24135
this.timestampFormat = timestampFormat;
25136
Flags = FrameFlags.FileAlterPreservation;
26137
}
27138

139+
/// <summary>
140+
/// Constructs and initializes a new instance of <see
141+
/// cref="EventTimeCodesFrame" /> by reading its raw data
142+
/// in a specified ID3v2 version.
143+
/// </summary>
144+
/// <param name="data">
145+
/// A <see cref="ByteVector" /> object starting with the raw
146+
/// representation of the new frame.
147+
/// </param>
148+
/// <param name="version">
149+
/// A <see cref="byte" /> indicating the ID3v2 version the
150+
/// raw frame is encoded in.
151+
/// </param>
28152
public EventTimeCodesFrame(ByteVector data,
29153
byte version) : base (data, version)
30154
{
31155
SetData(data, 0, version, true);
32156
}
33157

158+
159+
/// <summary>
160+
/// Constructs and initializes a new instance of <see
161+
/// cref="EventTimeCodesFrame" /> by reading its raw data
162+
/// in a specified ID3v2 version.
163+
/// </summary>
164+
/// <param name="frameHeader">
165+
/// A <see cref="FrameHeader" /> containing the header of the frame
166+
/// </param>
34167
public EventTimeCodesFrame(FrameHeader frameHeader) : base (frameHeader)
35168
{
36169

37170
}
38171

172+
173+
/// <summary>
174+
/// Constructs and initializes a new instance of <see
175+
/// cref="EventTimeCodesFrame" /> by reading its raw data
176+
/// in a specified ID3v2 version.
177+
/// </summary>
178+
/// <param name="data">
179+
/// A <see cref="ByteVector" /> object containing the raw
180+
/// representation of the new frame.
181+
/// </param>
182+
/// <param name="offset">
183+
/// A <see cref="int" /> indicating at what offset in
184+
/// <paramref name="data" /> the frame actually begins.
185+
/// </param>
186+
/// <param name="header">
187+
/// A <see cref="FrameHeader" /> containing the header of the
188+
/// frame found at <paramref name="offset" /> in the data.
189+
/// </param>
190+
/// <param name="version">
191+
/// A <see cref="byte" /> indicating the ID3v2 version the
192+
/// raw frame is encoded in.
193+
/// </param>
39194
public EventTimeCodesFrame(ByteVector data,
40195
int offset,
41196
FrameHeader header,
@@ -48,12 +203,25 @@ public EventTimeCodesFrame(ByteVector data,
48203

49204
#region Public Properties
50205

206+
/// <summary>
207+
/// Gets or sets the timestamp format for this frame instance.
208+
/// </summary>
209+
/// <value>
210+
/// A <see cref="TimestampFormat"/> that will be used in this frame instance.
211+
/// </value>
51212
public TimestampFormat TimestampFormat
52213
{
53214
get { return timestampFormat; }
54215
set { timestampFormat = value; }
55216
}
56217

218+
/// <summary>
219+
/// Gets or sets the events this frame contains.
220+
/// Each <see cref="EventTimeCode"/> represents a single event at a certain point in time.
221+
/// </summary>
222+
/// <value>
223+
/// A <see cref="List{EventTimeCode}"/> that are stored in this frame instance.
224+
/// </value>
57225
public List<EventTimeCode> Events
58226
{
59227
get { return events; }
@@ -104,6 +272,18 @@ public static EventTimeCodesFrame Get(Tag tag, bool create)
104272

105273
#region Protected Methods
106274

275+
/// <summary>
276+
/// Populates the values in the current instance by parsing
277+
/// its field data in a specified version.
278+
/// </summary>
279+
/// <param name="data">
280+
/// A <see cref="ByteVector" /> object containing the
281+
/// extracted field data.
282+
/// </param>
283+
/// <param name="version">
284+
/// A <see cref="byte" /> indicating the ID3v2 version the
285+
/// field data is encoded in.
286+
/// </param>
107287
protected override void ParseFields(ByteVector data, byte version)
108288
{
109289
events = new List<EventTimeCode>();
@@ -128,6 +308,18 @@ protected override void ParseFields(ByteVector data, byte version)
128308
}
129309
}
130310

311+
/// <summary>
312+
/// Renders the values in the current instance into field
313+
/// data for a specified version.
314+
/// </summary>
315+
/// <param name="version">
316+
/// A <see cref="byte" /> indicating the ID3v2 version the
317+
/// field data is to be encoded in.
318+
/// </param>
319+
/// <returns>
320+
/// A <see cref="ByteVector" /> object containing the
321+
/// rendered field data.
322+
/// </returns>
131323
protected override ByteVector RenderFields(byte version)
132324
{
133325
var data = new List<byte>();

0 commit comments

Comments
 (0)