midi-communications-macos 0.6.0 → 0.7.0

data/lib/midi-communications-macos/destination.rb

@@ -1,12 +1,33 @@
 module MIDICommunicationsMacOS
-  # Type of endpoint used for output
+  # MIDI output endpoint for sending MIDI messages.
+  #
+  # A Destination represents a MIDI output that can send messages to
+  # external MIDI devices or software. Messages can be sent as numeric
+  # bytes, hex strings, or arrays.
+  #
+  # @example Send a Note On/Off sequence
+  #   output = MIDICommunicationsMacOS::Destination.first
+  #   output.open
+  #   output.puts(0x90, 60, 100)  # Note On, middle C, velocity 100
+  #   sleep(0.5)
+  #   output.puts(0x80, 60, 0)    # Note Off
+  #
+  # @example Send as hex string
+  #   output.puts_s("903C64")     # Note On
+  #   output.puts_s("803C00")     # Note Off
+  #
+  # @see Source For receiving MIDI messages
+  # @see Endpoint For shared endpoint functionality
+  #
+  # @api public
   class Destination
     include Endpoint
 
     attr_reader :entity
 
-    # Close this output
-    # @return [Boolean]
+    # Closes this output.
+    #
+    # @return [Boolean] true if closed, false if already closed
     def close
       if @enabled
         @enabled = false
@@ -16,9 +37,14 @@ module MIDICommunicationsMacOS
       end
     end
 
-    # Send a MIDI message comprised of a String of hex digits
-    # @param [String] data A string of hex digits eg "904040"
-    # @return [Boolean]
+    # Sends a MIDI message as a hex string.
+    #
+    # @param data [String] hex string (e.g., "904040" for Note On)
+    # @return [Boolean] true on success
+    #
+    # @example
+    #   output.puts_s("904060")  # Note On
+    #   output.puts_s("804060")  # Note Off
     def puts_s(data)
       data = data.dup
       bytes = []
@@ -31,9 +57,13 @@ module MIDICommunicationsMacOS
     alias puts_bytestr puts_s
     alias puts_hex puts_s
 
-    # Send a MIDI message comprised of numeric bytes
-    # @param [*Integer] data Numeric bytes eg 0x90, 0x40, 0x40
-    # @return [Boolean]
+    # Sends a MIDI message as numeric bytes.
+    #
+    # @param data [Integer] numeric bytes (e.g., 0x90, 0x40, 0x40)
+    # @return [Boolean] true on success
+    #
+    # @example
+    #   output.puts_bytes(0x90, 0x40, 0x40)  # Note On
     def puts_bytes(*data)
       type = sysex?(data) ? :sysex : :small
       bytes = API.get_midi_packet(data)
@@ -41,9 +71,24 @@ module MIDICommunicationsMacOS
       true
     end
 
-    # Send a MIDI message of indeterminate type
-    # @param [*Array<Integer>, *Array<String>, *Integer, *String] args
-    # @return [Boolean]
+    # Sends a MIDI message in any supported format.
+    #
+    # Accepts multiple formats:
+    # - Numeric bytes: `puts(0x90, 0x40, 0x40)`
+    # - Array of bytes: `puts([0x90, 0x40, 0x40])`
+    # - Hex string: `puts("904040")`
+    #
+    # @param args [Array<Integer>, Array<String>, Integer, String] MIDI data
+    # @return [Boolean] true on success
+    #
+    # @example Send as bytes
+    #   output.puts(0x90, 60, 100)
+    #
+    # @example Send as array
+    #   output.puts([0x90, 60, 100])
+    #
+    # @example Send as hex string
+    #   output.puts("903C64")
     def puts(*args)
       case args.first
       when Array then args.each { |arg| puts(*arg) }
@@ -53,8 +98,19 @@ module MIDICommunicationsMacOS
     end
     alias write puts
 
-    # Enable this device
-    # @return [Destination]
+    # Opens this output for use.
+    #
+    # When a block is given, the output is automatically closed when
+    # the block exits.
+    #
+    # @yield [destination] optional block to execute with the open output
+    # @yieldparam destination [Destination] self
+    # @return [Destination] self
+    #
+    # @example Open with automatic close
+    #   output.open do |o|
+    #     o.puts(0x90, 60, 100)
+    #   end
     def enable
       @enabled ||= true
       if block_given?
@@ -69,20 +125,30 @@ module MIDICommunicationsMacOS
     alias open enable
     alias start enable
 
-    # Shortcut to the first output endpoint available
-    # @return [Destination]
+    # Returns the first available output endpoint.
+    #
+    # @return [Destination] the first destination
+    #
+    # @example
+    #   output = MIDICommunicationsMacOS::Destination.first
     def self.first
       Endpoint.first(:destination)
     end
 
-    # Shortcut to the last output endpoint available
-    # @return [Destination]
+    # Returns the last available output endpoint.
+    #
+    # @return [Destination] the last destination
     def self.last
       Endpoint.last(:destination)
     end
 
-    # All output endpoints
-    # @return [Array<Destination>]
+    # Returns all available output endpoints.
+    #
+    # @return [Array<Destination>] all destinations
+    #
+    # @example
+    #   outputs = MIDICommunicationsMacOS::Destination.all
+    #   outputs.each { |o| puts o.display_name }
     def self.all
       Endpoint.all_by_type[:destination]
     end

data/lib/midi-communications-macos/device.rb

@@ -1,17 +1,38 @@
 module MIDICommunicationsMacOS
-  # A MIDI device may have multiple logically distinct sub-components. For example, one device may
-  # encompass a MIDI synthesizer and a pair of MIDI ports, both addressable via a USB port. Each
-  # such element of a device is called a MIDI entity.
+  # Represents a physical or virtual MIDI device.
   #
-  # https://developer.apple.com/library/ios/documentation/CoreMidi/Reference/MIDIServices_Reference/Reference/reference.html
+  # A MIDI device may have multiple logically distinct sub-components. For example,
+  # one device may encompass a MIDI synthesizer and a pair of MIDI ports, both
+  # addressable via a USB port. Each such element of a device is called an {Entity}.
+  #
+  # Devices contain {Entity entities}, which in turn contain {Endpoint endpoints}
+  # ({Source sources} and {Destination destinations}).
+  #
+  # @example List all devices
+  #   MIDICommunicationsMacOS::Device.all.each do |device|
+  #     puts device.name
+  #   end
+  #
+  # @see https://developer.apple.com/documentation/coremidi/midideviceref
+  #
+  # @api public
   class Device
+    # @!attribute [r] entities
+    #   @return [Array<Entity>] the device's entities
+    # @!attribute [r] id
+    #   @return [Integer] unique numeric ID
+    # @!attribute [r] name
+    #   @return [String] device name from Core MIDI
     attr_reader :entities,
-                :id, # Unique Numeric id
-                :name # Device name from midi-communications-macos
+                :id,
+                :name
 
-    # @param [Integer] id The ID for the device
-    # @param [Object] device_pointer The underlying device pointer
-    # @param [Boolean] include_offline Whether to include offline entities (default: false)
+    # Creates a new Device wrapper.
+    #
+    # @param id [Integer] the device ID
+    # @param device_pointer [FFI::Pointer] pointer to the Core MIDI device
+    # @param include_offline [Boolean] whether to include offline entities
+    # @api private
     def initialize(id, device_pointer, include_offline: false)
       @id = id
       @resource = device_pointer
@@ -19,8 +40,9 @@ module MIDICommunicationsMacOS
       populate(include_offline: include_offline)
     end
 
-    # Endpoints for this device
-    # @return [Array<Endpoint>]
+    # Returns all endpoints for this device, grouped by type.
+    #
+    # @return [Hash{Symbol => Array<Endpoint>}] hash with :source and :destination keys
     def endpoints
       endpoints = { source: [], destination: [] }
       endpoints.each_key do |key|
@@ -39,11 +61,19 @@ module MIDICommunicationsMacOS
       id
     end
 
-    # All cached devices
-    # @param [Hash] options The options to select devices with
-    # @option options [Boolean] :cache If false, the device list will never be cached. This would be useful if one needs to alter the device list (e.g. plug in a USB MIDI interface) while their program is running.
-    # @option options [Boolean] :include_offline If true, devices marked offline by midi-communications-macos will be included in the list
-    # @return [Array<Device>] All cached devices
+    # Returns all available MIDI devices.
+    #
+    # Devices are cached by default. Use `cache: false` to refresh, or call
+    # {.refresh} to clear the cache.
+    #
+    # @param options [Hash] options for device selection
+    # @option options [Boolean] :cache (true) whether to use cached devices
+    # @option options [Boolean] :include_offline (false) include offline devices
+    # @return [Array<Device>] all available devices
+    #
+    # @example
+    #   devices = MIDICommunicationsMacOS::Device.all
+    #   devices.each { |d| puts d.name }
     def self.all(options = {})
       use_cache = options[:cache] || true
       include_offline = options[:include_offline] || false
@@ -60,8 +90,12 @@ module MIDICommunicationsMacOS
       @devices
     end
 
-    # Refresh the Device cache. This is needed if, for example a USB MIDI device is plugged in while the program is running
-    # @return [Array<Device>] The Device cache
+    # Clears the device cache.
+    #
+    # Call this when MIDI devices are plugged in or unplugged while the
+    # program is running, then call {.all} to get the updated list.
+    #
+    # @return [Array<Device>] the cleared cache (empty array)
     def self.refresh
       @devices.clear
       @devices

data/lib/midi-communications-macos/endpoint.rb

@@ -1,18 +1,44 @@
 module MIDICommunicationsMacOS
-  # A source or destination of a 16-channel MIDI stream
+  # A source or destination of a 16-channel MIDI stream.
   #
-  # https://developer.apple.com/library/ios/documentation/CoreMidi/Reference/MIDIServices_Reference/Reference/reference.html
+  # This module provides shared functionality for both {Source} (input) and
+  # {Destination} (output) endpoints. Each endpoint represents a single
+  # point of MIDI communication within an {Entity}.
+  #
+  # @see https://developer.apple.com/documentation/coremidi/midiendpointref
+  #
+  # @api public
   module Endpoint
     extend Forwardable
 
-    attr_reader :enabled, # has the endpoint been initialized?
+    # @!attribute [r] enabled
+    #   @return [Boolean] whether the endpoint has been initialized
+    # @!attribute [r] entity
+    #   @return [Entity] the parent entity
+    # @!attribute [r] id
+    #   @return [Integer] unique local numeric ID of the endpoint
+    # @!attribute [r] resource_id
+    #   @return [Integer] Core MIDI resource identifier
+    # @!attribute [r] type
+    #   @return [Symbol] endpoint type (:source or :destination)
+    attr_reader :enabled,
                 :entity,
-                :id, # unique local Numeric id of the endpoint
-                :resource_id, # :input or :output
+                :id,
+                :resource_id,
                 :type
 
+    # @!method manufacturer
+    #   @return [String] device manufacturer name (delegated to entity)
+    # @!method model
+    #   @return [String] device model name (delegated to entity)
+    # @!method name
+    #   @return [String] endpoint name (delegated to entity)
+    # @!method display_name
+    #   @return [String] formatted display name (delegated to entity)
     def_delegators :entity, :manufacturer, :model, :name, :display_name
 
+    # @!method enabled?
+    #   @return [Boolean] alias for {#enabled}
     alias enabled? enabled
 
     # @param [Integer] resource_id

data/lib/midi-communications-macos/entity.rb

@@ -1,12 +1,26 @@
 module MIDICommunicationsMacOS
-  # A MIDI entity can have any number of MIDI endpoints, each of which is a source or destination
-  # of a 16-channel MIDI stream. By grouping a device's endpoints into entities, the system has
-  # enough information for an application to make reasonable default assumptions about how to
-  # communicate in a bi-directional manner with each entity, as is necessary in MIDI librarian
-  # applications.
+  # A logical grouping of MIDI endpoints within a device.
   #
-  # https://developer.apple.com/library/ios/documentation/CoreMidi/Reference/MIDIServices_Reference/Reference/reference.html
+  # A MIDI entity can have any number of MIDI endpoints, each of which is a
+  # {Source source} or {Destination destination} of a 16-channel MIDI stream.
+  # By grouping a device's endpoints into entities, the system has enough
+  # information for applications to make reasonable default assumptions about
+  # bidirectional communication.
+  #
+  # @see https://developer.apple.com/documentation/coremidi/midientityref
+  #
+  # @api public
   class Entity
+    # @!attribute [r] endpoints
+    #   @return [Hash{Symbol => Array<Endpoint>}] endpoints grouped by :source and :destination
+    # @!attribute [r] manufacturer
+    #   @return [String] device manufacturer name
+    # @!attribute [r] model
+    #   @return [String] device model name
+    # @!attribute [r] name
+    #   @return [String] entity name
+    # @!attribute [r] resource
+    #   @return [FFI::Pointer] pointer to the Core MIDI entity
     attr_reader :endpoints,
                 :manufacturer,
                 :model,

data/lib/midi-communications-macos/source.rb

@@ -1,8 +1,40 @@
 module MIDICommunicationsMacOS
-  # Type of endpoint used for input
+  # MIDI input endpoint for receiving MIDI messages.
+  #
+  # A Source represents a MIDI input that can receive messages from
+  # external MIDI devices or software. Messages are queued and can
+  # be retrieved using {#gets} or {#gets_s}.
+  #
+  # @example Open and read from the first input
+  #   input = MIDICommunicationsMacOS::Source.first
+  #   input.open
+  #   messages = input.gets
+  #   # => [{ data: [144, 60, 100], timestamp: 1234567890.123 }]
+  #
+  # @example Read messages as hex strings
+  #   messages = input.gets_s
+  #   # => [{ data: "903C64", timestamp: 1234567890.123 }]
+  #
+  # @see Destination For sending MIDI messages
+  # @see Endpoint For shared endpoint functionality
+  #
+  # @api public
   class Source
     include Endpoint
 
+    # Reads MIDI messages from the input buffer.
+    #
+    # Returns an array of MIDI event hashes. Each hash contains:
+    # - `:data` - Array of numeric bytes (e.g., [144, 60, 100])
+    # - `:timestamp` - Float timestamp when the message was received
+    #
+    # This method blocks until at least one message is available.
+    #
+    # @return [Array<Hash>] array of MIDI event hashes
+    #
+    # @example
+    #   messages = input.gets
+    #   # => [{ data: [144, 60, 100], timestamp: 1024.5 }]
     #
     # An array of MIDI event hashes as such:
     #   [
@@ -20,15 +52,17 @@ module MIDICommunicationsMacOS
     end
     alias read gets
 
-    # Same as Source#gets except that it returns message data as string of hex
-    # digits as such:
-    #   [
-    #     { data: "904060", timestamp: 904 },
-    #     { data: "804060", timestamp: 1150 },
-    #     { data: "90447F", timestamp: 1300 }
-    #   ]
+    # Reads MIDI messages as hex strings.
     #
-    # @return [Array<Hash>]
+    # Same as {#gets} but returns message data as hex strings instead
+    # of byte arrays.
+    #
+    # @return [Array<Hash>] array of MIDI event hashes with hex string data
+    #
+    # @example
+    #   messages = input.gets_s
+    #   # => [{ data: "904060", timestamp: 904 },
+    #   #     { data: "804060", timestamp: 1150 }]
     def gets_s
       messages = gets
       messages.each do |message|
@@ -38,8 +72,23 @@ module MIDICommunicationsMacOS
     end
     alias gets_bytestr gets_s
 
-    # Enable this the input for use; can be passed a block
-    # @return [Source]
+    # Opens this input for use.
+    #
+    # When a block is given, the input is automatically closed when
+    # the block exits.
+    #
+    # @yield [source] optional block to execute with the open input
+    # @yieldparam source [Source] self
+    # @return [Source] self
+    #
+    # @example Open with automatic close
+    #   input.open do |i|
+    #     messages = i.gets
+    #   end
+    #
+    # @example Open manually
+    #   input.open
+    #   messages = input.gets
     def enable
       @enabled ||= true
       if block_given?
@@ -54,8 +103,9 @@ module MIDICommunicationsMacOS
     alias open enable
     alias start enable
 
-    # Close this input
-    # @return [Boolean]
+    # Closes this input.
+    #
+    # @return [Boolean] true if closed, false if already closed
     def close
       #error = API.MIDIPortDisconnectSource( @handle, @resource )
       #raise "MIDIPortDisconnectSource returned error code #{error}" unless error.zero?
@@ -73,20 +123,30 @@ module MIDICommunicationsMacOS
       end
     end
 
-    # Shortcut to the first available input endpoint
-    # @return [Source]
+    # Returns the first available input endpoint.
+    #
+    # @return [Source] the first source
+    #
+    # @example
+    #   input = MIDICommunicationsMacOS::Source.first
     def self.first
       Endpoint.first(:source)
     end
 
-    # Shortcut to the last available input endpoint
-    # @return [Source]
+    # Returns the last available input endpoint.
+    #
+    # @return [Source] the last source
     def self.last
       Endpoint.last(:source)
     end
 
-    # All input endpoints
-    # @return [Array<Source>]
+    # Returns all available input endpoints.
+    #
+    # @return [Array<Source>] all sources
+    #
+    # @example
+    #   inputs = MIDICommunicationsMacOS::Source.all
+    #   inputs.each { |i| puts i.display_name }
     def self.all
       Endpoint.all_by_type[:source]
     end

data/lib/midi-communications-macos/type_conversion.rb

@@ -1,11 +1,18 @@
 module MIDICommunicationsMacOS
-  # Helper for convertig MIDI data
+  # Utility methods for converting between MIDI data formats.
+  #
+  # @api public
   module TypeConversion
     extend self
 
-    # Convert an array of numeric byes to a hex string (e.g. [0x90, 0x40, 0x40] becomes "904040")
-    # @param [Array<Integer>] bytes
-    # @return [String]
+    # Converts an array of numeric bytes to a hex string.
+    #
+    # @param bytes [Array<Integer>] array of numeric bytes (e.g., [0x90, 0x40, 0x40])
+    # @return [String] uppercase hex string (e.g., "904040")
+    #
+    # @example
+    #   TypeConversion.numeric_bytes_to_hex_string([0x90, 0x40, 0x40])
+    #   # => "904040"
     def numeric_bytes_to_hex_string(bytes)
       string_bytes = bytes.map do |byte|
         str = byte.to_s(16).upcase

data/lib/midi-communications-macos/version.rb

@@ -0,0 +1,4 @@
+module MIDICommunicationsMacOS
+  # Current version of the midi-communications-macos gem.
+  VERSION = '0.7.0'.freeze
+end

data/lib/midi-communications-macos.rb

@@ -21,6 +21,44 @@ require 'midi-communications-macos/device'
 require 'midi-communications-macos/source'
 require 'midi-communications-macos/destination'
 
+require_relative 'midi-communications-macos/version'
+
+# macOS-specific MIDI I/O using the Core MIDI framework.
+#
+# This library provides low-level access to MIDI devices on macOS through
+# Apple's Core MIDI framework via FFI bindings. It is typically used through
+# the higher-level {https://github.com/javier-sy/midi-communications midi-communications} gem.
+#
+# The main classes are:
+# - {Source} - MIDI input endpoints for receiving messages
+# - {Destination} - MIDI output endpoints for sending messages
+# - {Device} - Physical or virtual MIDI devices
+# - {Entity} - Logical groupings of endpoints within a device
+#
+# @example List all MIDI sources (inputs)
+#   MIDICommunicationsMacOS::Source.all.each do |source|
+#     puts "#{source.id}: #{source.display_name}"
+#   end
+#
+# @example List all MIDI destinations (outputs)
+#   MIDICommunicationsMacOS::Destination.all.each do |dest|
+#     puts "#{dest.id}: #{dest.display_name}"
+#   end
+#
+# @example Send a MIDI message
+#   output = MIDICommunicationsMacOS::Destination.first
+#   output.open
+#   output.puts(0x90, 60, 100)  # Note On
+#   output.puts(0x80, 60, 0)    # Note Off
+#
+# @example Receive MIDI messages
+#   input = MIDICommunicationsMacOS::Source.first
+#   input.open
+#   messages = input.gets
+#   # => [{ data: [144, 60, 100], timestamp: 1234567890.123 }]
+#
+# @see https://developer.apple.com/documentation/coremidi Apple Core MIDI Documentation
+#
+# @api public
 module MIDICommunicationsMacOS
-  VERSION = '0.5.4'.freeze
 end

data/midi-communications-macos.gemspec

@@ -1,30 +1,34 @@
+require_relative 'lib/midi-communications-macos/version'
+
 Gem::Specification.new do |s|
   s.name        = 'midi-communications-macos'
-  s.version     = '0.6.0'
+  s.version     = MIDICommunicationsMacOS::VERSION
   s.date        = '2025-08-23'
   s.summary     = 'Realtime MIDI IO with Ruby for OSX'
   s.description = 'Access the Apple Core MIDI framework API with Ruby.'
   s.authors     = ['Javier Sánchez Yeste']
   s.email       = ['javier.sy@gmail.com']
   s.files       = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  s.homepage    = 'https://rubygems.org/gems/midi-communications-macos'
-  s.license     = 'LGPL-3.0'
+  s.homepage    = 'https://github.com/javier-sy/midi-communications-macos'
+  s.license     = 'LGPL-3.0-or-later'
 
   s.required_ruby_version = '>= 2.7'
 
-  # TODO
-  #s.metadata    = {
-  # "source_code_uri" => "https://",
-  # "homepage_uri" => "",
-  # "documentation_uri" => "",
-  # "changelog_uri" => ""
-  #}
+  s.metadata = {
+    'homepage_uri' => s.homepage,
+    'source_code_uri' => s.homepage,
+    'documentation_uri' => 'https://www.rubydoc.info/gems/midi-communications-macos'
+  }
 
   s.add_runtime_dependency 'ffi', '~> 1.15', '>= 1.15.4'
 
   s.add_development_dependency 'minitest', '~>5', '>= 5.14.4'
   s.add_development_dependency 'rake', '~>13', '>= 13.0.6'
   s.add_development_dependency 'shoulda-context', '~>2', '>= 2.0.0'
+
+  s.add_development_dependency 'yard', '~> 0.9'
+  s.add_development_dependency 'redcarpet', '~> 3.6'
+  s.add_development_dependency 'webrick', '~> 1.8'
 end