Permalink
Browse files

Adding/improving class documentation

  • Loading branch information...
1 parent 70234da commit a6abddd65cdf33cc3154a345da4374ad85a0aee4 @jstrait jstrait committed Mar 13, 2011
Showing with 36 additions and 6 deletions.
  1. +11 −3 lib/audioengine.rb
  2. +5 −0 lib/pattern.rb
  3. +8 −0 lib/song.rb
  4. +6 −3 lib/songparser.rb
  5. +6 −0 lib/track.rb
View
@@ -1,6 +1,14 @@
-# This class actually generates the output sound data for the performance.
-# Applies a Kit to a Song (which contains sub Patterns and Tracks) to
-# produce output sample data.
+# This class actually generates the output audio data that is saved to disk.
+#
+# To produce audio data, it needs two things: a Song and a Kit. The Song tells
+# it which notes to play and when, while the Kit provides the sample data to
+# use for each instrument's notes.
+#
+# Example usage, assuming song and kit are already defined:
+#
+# engine = AudioEngine.new(song, kit)
+# engine.write_to_file("my_song.wav")
+#
class AudioEngine
SAMPLE_RATE = 44100
PACK_CODE = "s*" # All output sample data is assumed to be 16-bit
View
@@ -1,3 +1,8 @@
+# Domain object which models one or more Tracks playing a part of the song at the same time.
+# For example, a bass drum, snare drum, and hi-hat track playing the song's chorus.
+#
+# This object is like sheet music; the AudioEngine is responsible creating actual
+# audio data for a Pattern (with the help of a Kit).
class Pattern
FLOW_TRACK_NAME = "flow"
View
@@ -1,5 +1,13 @@
class InvalidTempoError < RuntimeError; end
+
+# Domain object which models the 'sheet music' for a full song. Models the Patterns
+# that should be played, in which order (i.e. the flow), and at which tempo.
+#
+# This is the top-level model object that is used by the AudioEngine to produce
+# actual audio data. A Song tells the AudioEngine what notes to play and when,
+# while a Kit provides the sample data to use for each note. With a Song and a Kit
+# the AudioEngine can produce the audio data that is stored to disk.
class Song
DEFAULT_TEMPO = 120
View
@@ -1,9 +1,12 @@
class SongParseError < RuntimeError; end
-# This class is used to parse a raw YAML song definition into domain objects. These
-# domain objects can then be used by AudioEngine to generate the output sample data
-# for the song.
+# This class is used to parse a raw YAML song definition into domain objects (i.e.
+# Song, Pattern, Track, and Kit). These domain objects can then be used by AudioEngine
+# to generate the actual audio data that is saved to disk.
+#
+# The sole public method is parse(). It takes a raw YAML string and returns a Song and
+# Kit object (or raises an error if the YAML string couldn't be parsed correctly).
class SongParser
DONT_USE_STRUCTURE_WARNING =
"\n" +
View
@@ -1,5 +1,11 @@
class InvalidRhythmError < RuntimeError; end
+
+# Domain object which models a kit sound playing a rhythm. For example,
+# a bass drum playing every quarter note for two measures.
+#
+# This object is like sheet music; the AudioEngine is responsible creating actual
+# audio data for a Track (with the help of a Kit).
class Track
REST = "."
BEAT = "X"

0 comments on commit a6abddd

Please sign in to comment.