midi-communications 0.6.1 → 0.7.0

data/lib/midi-communications/loader.rb

@@ -1,18 +1,27 @@
 module MIDICommunications
-
-  # Populate UniMIDI devices using the underlying device objects from the platform-specific gems
+  # Populates MIDI devices using platform-specific adapters.
+  #
+  # This class lazily loads and caches MIDI devices from the underlying
+  # platform adapter (macOS, Linux, Windows, or JRuby).
+  #
+  # @api private
   class Loader
     class << self
-      # Use the given platform-specific adapter to load devices
-      # @param [MIDICommunications::Adapter::Loader] loader
+      # Sets the platform-specific loader to use.
+      #
+      # @param loader [Module] a loader module with `inputs` and `outputs` methods
+      # @return [Module] the loader
       def use(loader)
         @loader = loader
       end
 
-      # Get all MIDI devices
-      # @param [Hash] options
-      # @option options [Symbol] :direction Return only a particular direction of device eg :input, :output
-      # @return [Array<Input>, Array<Output>]
+      # Returns all MIDI devices, optionally filtered by direction.
+      #
+      # Lazily loads and caches devices from the platform adapter on first call.
+      #
+      # @param options [Hash] filter options
+      # @option options [Symbol] :direction Return only :input or :output devices
+      # @return [Array<Input>, Array<Output>] array of devices
       def devices(options = {})
         if @devices.nil?
           inputs = @loader.inputs.map { |device| ::MIDICommunications::Input.new(device) }

data/lib/midi-communications/output.rb

@@ -1,27 +1,69 @@
 module MIDICommunications
-
-  # A MIDI output device
+  # A MIDI output device for sending MIDI messages.
+  #
+  # Output devices send MIDI data to external instruments, software synthesizers,
+  # or other MIDI destinations. Use the class methods to discover and select
+  # available output devices.
+  #
+  # @example List available outputs
+  #   MIDICommunications::Output.list
+  #
+  # @example Send a note to the first output
+  #   output = MIDICommunications::Output.first
+  #   output.puts(0x90, 60, 100)  # Note On, middle C, velocity 100
+  #   sleep(0.5)
+  #   output.puts(0x80, 60, 0)    # Note Off
+  #
+  # @example Send messages as hex strings
+  #   output = MIDICommunications::Output.first
+  #   output.puts_s("904060")     # Note On
+  #   output.puts_s("804060")     # Note Off
+  #
+  # @example Interactive selection
+  #   output = MIDICommunications::Output.gets
+  #
+  # @example Find by name
+  #   output = MIDICommunications::Output.find_by_name("IAC Driver Bus 1")
+  #   output.open
+  #
+  # @see Input For receiving MIDI messages
+  #
+  # @api public
   class Output
     extend Device::ClassMethods
     include Device::InstanceMethods
 
-    # All MIDI output devices -- used to populate the class
-    # @return [Array<Output>]
+    # Returns all available MIDI output devices.
+    #
+    # @return [Array<Output>] array of output devices
+    #
+    # @example
+    #   outputs = MIDICommunications::Output.all
+    #   outputs.each { |o| puts o.name }
     def self.all
       Loader.devices(direction: :output)
     end
 
-    # Sends a message to the output.
+    # Sends a MIDI message to the output.
     #
-    # The message format can be:
+    # Accepts multiple message formats for flexibility:
+    # - Numeric bytes: `output.puts(0x90, 0x40, 0x40)`
+    # - Array of numeric bytes: `output.puts([0x90, 0x40, 0x40])`
+    # - Hex string: `output.puts("904040")`
+    # - Array of strings: `output.puts(["904040", "804040"])`
+    # - Objects with `to_bytes` method: `output.puts(midi_event)`
     #
-    # 1. Numeric bytes eg output.puts(0x90, 0x40, 0x40)
-    # 2. An array of numeric bytes [0x90, 0x40, 0x40]
-    # 3. A string of bytes eg "904040"
-    # 4. An array of strings ["904040", "804040"]
+    # @param messages [Array<Integer>, Array<String>, Integer, String] MIDI messages in any supported format
+    # @return [Array<Integer>, Array<String>] the messages sent
     #
-    # @param [*Array<Integer>, *Array<String>, *Integer, *String] messages
-    # @return [Array<Integer>, Array<String>]
+    # @example Send Note On as bytes
+    #   output.puts(0x90, 60, 100)
+    #
+    # @example Send Note On as array
+    #   output.puts([0x90, 60, 100])
+    #
+    # @example Send Note On as hex string
+    #   output.puts("903C64")
     def puts(*messages)
       message = messages.first
       case message
@@ -37,10 +79,17 @@ module MIDICommunications
       end
     end
 
-    # Sends a message to the output in a form of a string eg "904040".  This method does not do
-    # type checking
-    # @param [*String] messages
-    # @return [Array<String>, Array<Array<String>>]
+    # Sends a MIDI message as a hex string.
+    #
+    # This is a lower-level method that does not perform type checking.
+    # Use {#puts} for automatic format detection.
+    #
+    # @param messages [String] one or more hex strings (e.g., "904040")
+    # @return [String, Array<String>] the message(s) sent
+    #
+    # @example
+    #   output.puts_s("904060")  # Note On
+    #   output.puts_s("804060")  # Note Off
     def puts_s(*messages)
       @device.puts_s(*messages)
       messages.count < 2 ? messages[0] : messages
@@ -48,10 +97,16 @@ module MIDICommunications
     alias puts_bytestr puts_s
     alias puts_hex puts_s
 
-    # Sends a message to the output in a form of bytes eg output.puts_bytes(0x90, 0x40, 0x40).
-    # This method does not do type checking.
-    # @param [*Array<Integer>] messages
-    # @return [Array<Integer>, Array<Array<Integer>>]
+    # Sends a MIDI message as numeric bytes.
+    #
+    # This is a lower-level method that does not perform type checking.
+    # Use {#puts} for automatic format detection.
+    #
+    # @param messages [Integer] numeric byte values (e.g., 0x90, 0x40, 0x40)
+    # @return [Integer, Array<Integer>] the message bytes sent
+    #
+    # @example
+    #   output.puts_bytes(0x90, 0x40, 0x40)  # Note On, note 64, velocity 64
     def puts_bytes(*messages)
       @device.puts_bytes(*messages)
       messages.count < 2 ? messages[0] : messages

data/lib/midi-communications/platform.rb

@@ -1,10 +1,19 @@
 module MIDICommunications
-
-  # Deal with different dependencies between different user environments
+  # Handles platform detection and adapter loading.
+  #
+  # Automatically detects the current platform (macOS, Linux, Windows, JRuby)
+  # and loads the appropriate low-level MIDI adapter.
+  #
+  # @api private
   module Platform
     extend self
 
-    # Loads the proper MIDI library and adapter for the user's environment
+    # Loads the correct MIDI adapter for the current platform.
+    #
+    # Called automatically when the library is required. Detects the
+    # platform and loads the corresponding adapter gem.
+    #
+    # @return [void]
     def bootstrap
       require("midi-communications/adapter/#{platform_lib}")
       Loader.use(platform_module::Loader)

data/lib/midi-communications/type_conversion.rb

@@ -1,12 +1,18 @@
 module MIDICommunications
-
-  # Utility for converting between different data formats
+  # Utility methods for converting between MIDI data formats.
+  #
+  # @api public
   module TypeConversion
     extend self
 
-    # Convert an array of numeric bytes to string of hex bytes
-    # @param [Array<Integer>] bytes An array of numeric bytes eg [0x90, 0x40, 0x40]
-    # @return [String] A string of hex bytes eg "904040"
+    # 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] hex string representation (e.g., "904040")
+    #
+    # @example
+    #   TypeConversion.numeric_byte_array_to_hex_string([0x90, 0x40, 0x40])
+    #   # => "904040"
     def numeric_byte_array_to_hex_string(bytes)
       bytes.map { |b| b.to_s(16) }.join
     end

data/lib/midi-communications/version.rb

@@ -1,3 +1,4 @@
 module MIDICommunications
-  VERSION = '0.6.1'.freeze
+  # Current version of the midi-communications gem.
+  VERSION = '0.7.0'.freeze
 end

data/lib/midi-communications.rb

@@ -18,6 +18,44 @@ require 'midi-communications/output'
 
 require_relative 'midi-communications/version'
 
+# Platform-independent realtime MIDI input and output for Ruby.
+#
+# MIDICommunications provides a unified API for MIDI communication across
+# different platforms (macOS, Linux, Windows, JRuby). It automatically
+# detects the current platform and loads the appropriate low-level adapter.
+#
+# This library is part of the MusaDSL MIDI suite:
+# - {https://github.com/javier-sy/midi-events MIDI Events} - MIDI message representation
+# - {https://github.com/javier-sy/midi-parser MIDI Parser} - MIDI data parsing
+# - {https://github.com/javier-sy/midi-communications MIDI Communications} - MIDI I/O (this library)
+# - {https://github.com/javier-sy/midi-communications-macos MIDI Communications MacOS} - macOS adapter
+#
+# @example List all MIDI outputs
+#   MIDICommunications::Output.list
+#   # 0) IAC Driver Bus 1
+#   # 1) USB MIDI Device
+#
+# @example Send a note to the first output
+#   output = MIDICommunications::Output.first
+#   output.puts(0x90, 60, 100)  # Note On, middle C, velocity 100
+#   sleep(0.5)
+#   output.puts(0x80, 60, 0)    # Note Off
+#
+# @example Receive MIDI from an input
+#   input = MIDICommunications::Input.first
+#   loop do
+#     messages = input.gets
+#     messages.each { |m| puts m.inspect }
+#   end
+#
+# @example Interactive device selection
+#   output = MIDICommunications::Output.gets  # Prompts user to select
+#   input = MIDICommunications::Input.gets
+#
+# @see Input MIDI input device class
+# @see Output MIDI output device class
+#
+# @api public
 module MIDICommunications
   Platform.bootstrap
 end

data/midi-communications.gemspec

@@ -9,20 +9,18 @@ Gem::Specification.new do |s|
   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'
+  s.homepage    = 'https://github.com/javier-sy/midi-communications'
   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'
+  }
 
-  s.add_runtime_dependency 'midi-communications-macos', '~> 0.6'
+  s.add_runtime_dependency 'midi-communications-macos', '~> 0.7'
   # s.add_runtime_dependency  'alsa-rawmidi', '~> 0.3', '>= 0.3.1'
   # s.add_runtime_dependency  'midi-jruby', '~> 0.1', '>= 0.1.4'
   # s.add_runtime_dependency  'midi-winmm', '~> 0.1', '>= 0.1.10'
@@ -30,4 +28,8 @@ Gem::Specification.new do |s|
   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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: midi-communications
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Javier Sánchez Yeste
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -83,6 +83,48 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 2.0.0
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
 description: Access MIDI devices for MacOS, Linux (wip), Windows (wip) and JRuby (wip).
 email:
 - javier.sy@gmail.com
@@ -91,6 +133,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".version"
+- ".yardopts"
 - Gemfile
 - LICENSE
 - LICENSE.unimidi
@@ -114,10 +158,13 @@ files:
 - lib/midi-communications/type_conversion.rb
 - lib/midi-communications/version.rb
 - midi-communications.gemspec
-homepage: https://rubygems.org/gems/midi-communications
+homepage: https://github.com/javier-sy/midi-communications
 licenses:
 - LGPL-3.0-or-later
-metadata: {}
+metadata:
+  homepage_uri: https://github.com/javier-sy/midi-communications
+  source_code_uri: https://github.com/javier-sy/midi-communications
+  documentation_uri: https://www.rubydoc.info/gems/midi-communications
 rdoc_options: []
 require_paths:
 - lib