Using Ruby coreaudio gem - objective-c

Question

I'm creating an audio project as an academic exercise - I want to use Ruby for a non-rails project. I came across the coreaudio gem here: https://github.com/nagachika/ruby-coreaudio and thought it would be useful in playing back the audio I'm creating. However, there are some basic things I'm just not getting about this gem.
1) Is there any documentation? I would be happy to volunteer to contribute to the project by writing documentation but I'm afraid I lack the basic understanding to do so. I looked at the generated documentation here: http://rubydoc.info/gems/coreaudio/ but that's only more mysterious. I would think that would at least show the method prototypes but I only see one method CoreAudio::AudioFile:read. The examples have calls to other methods that don't show up here.
2) What are the available methods / is there an API? The examples have things like CoreAudio.default_input_device.input_buffer and CoreAudio.default_output_device.output_stream, and by copying the examples I have been able to get some sound out through the CoreAudio.default_output_device.output_buffer. default_input_device and default_output_device are instances of CoreAudio::AudioDevice. This is awesome, but I don't know what CoreAudio::AudioDevice is.
3) What is CoreAudio::AudioDevice? Having no more sophisticated tools at my disposal I grepped for the string 'AudioDevice' in the installed gem files. I found a number of instances in the file /ext/coreaudio.m. The code looks like C and I think .m is a file suffix for a certain type of file in an Objective C project. The only place in that file where I see the string 'AudioDevice' where it isn't part of a larger variable name (eg: rb_cAudioDevice) is in the comments, but I'm guessing that this objective C code gets compiled into... I don't know what...
4) What are these Objective C files doing here? Where's the Ruby? Shouldn't there be a file or files written in Ruby somewhere in this project that define the class CoreAudio::AudioDevice? The only .rb file on any appreciable size is lib/coreaudio/audiofile.rb (where the read method is defined, the only method shown in rdoc).
5) What is coreaudio_ext.bundle? The gem installation process created a binary file called coreaudio_ext.bundle which, if I had to guess, would be the result of compiling the objective C files in the project. This file is required in lib/coreaudio/coreaudio.rb, so must be significant to Ruby, but it's a black box to me. I assume it is a black box containing the definition of the ephemeral CoreAudio::AudioDevice. How would I know how to use this other than looking at the examples?
Please help me understand what I'm missing.

Answer 1

Since I asked, I'll attempt to document my answer for any future archaeologists who may puzzle with the same questions. Thanks to Neil Slater, for pointing me in the direction of important resources needed to answer my question(s).
1) Is there any documentation? - not really. The CoreAudio::AudioFile:read function is the only one documented by rdoc because everything else is implemented in a Ruby extension in C, by the mechanism described in detail here: http://media.pragprog.com/titles/ruby3/ext_ruby.pdf. Turns out that this process has been done for a great number of existing C libraries to add their functionality to Ruby.
2) What are the available methods / is there an API? - The extension created is the equivalent of the following: (corrections welcome)
Module CoreAudio
class AudioDevice
attr_reader :devid, :name, :available_sample_rate, :nominal_rate, :input_stream, :output_stream
def initialize(devIdVal, options)
...
end
def actual_rate
...
end
def output_loop(frame)
...
end
def output_buffer(frame)
...
end
def input_buffer(frame)
...
end
end
class AudioStream
attr_reader :channels, :buffer_frame_size
def initialize(devid_val, is_input)
...
end
end
class OutLoop
def []=(index, val)
...
end
def start
...
end
def stop
...
end
end
class AudioBuffer
def start
...
end
def stop
...
end
def dropped_frame
...
end
def reset_dropped_frame
...
end
def space
...
end
end
class OutputBuffer
def <<(nary)
...
end
end
class InputBuffer
def read(num)
...
end
end
def devices
...
end
def default_input_device
...
end
def default_output_device
...
end
def set_default_output_device
...
end
class AudioFile
def initialize
...
end
def close
...
end
def write(data)
...
end
def read_frames(frame_val)
...
end
def rate
...
end
def channels
...
end
def inner_rate
...
end
def inner_channels
...
end
end
end
3) What is CoreAudio::AudioDevice? - I was mistaken about the string "AudioDevice" not appearing on its own as an identifier - it appears in the C code as follows:
rb_cAudioDevice = rb_define_class_under(rb_mCoreAudio, "AudioDevice", rb_cObject);
this is declaring the class AudioDevice inside of module CoreAudio.
4) Where's the Ruby? - this gem is extending Ruby with coreaudio, written in C.
5) What is coreaudio_ext.bundle? this is the compiled C code. It's required by the gem in coreaudio.rb
require "coreaudio/coreaudio_ext"
A .bundle file is the Mac equivalent of a .dll file in Windows. (I don't believe there is a Windows implementation of this gem, as CoreAudio is a Mac-specific technology)