Improve code style using Rubocop

* Rubocop styles

* Deprecate setters and getters for code style

  Switches to better Ruby-style getters and setters instead of blindly copying
  the HID Api style

* Improve code style line lengths

* Improve documentation

Author: Gareth Adams

.rubocop.yml

@@ -0,0 +1,26 @@
+AllCops:
+  DisplayCopNames: true
+  DisplayStyleGuide: true
+  TargetRubyVersion: 2.3
+
+Metrics/LineLength:
+  Max: 90
+
+# This cop is enabled when TargetRubyVersion is 2.3 or higher
+#
+# Implementing its advice will help with Ruby 3.0 compatibility, but isn't a
+# trivial change, and could cause problems before gems are updated to properly
+# handle frozen strings.
+#
+# See: https://wyeworks.com/blog/2015/12/1/immutable-strings-in-ruby-2-dot-3
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+  StyleGuide: https://www.viget.com/articles/just-use-double-quoted-ruby-strings
+
+# This is one part of the style guide that doesn't express a preference, it just
+# suggests you make a choice
+Style/DotPosition:
+  EnforcedStyle: trailing

Gemfile

@@ -1,4 +1,4 @@
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
 # Specify your gem's dependencies in hid_api.gemspec
 gemspec

Rakefile

@@ -1,9 +1,6 @@
 require "bundler/gem_tasks"
 
-begin
-  require 'rspec/core/rake_task'
-  RSpec::Core::RakeTask.new(:spec)
-rescue LoadError
-end
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec

hid_api.gemspec

@@ -1,7 +1,7 @@
 # coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'hid_api/version'
+require "hid_api/version"
 
 Gem::Specification.new do |spec|
   spec.name          = "hid_api"
@@ -10,11 +10,13 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Gareth Adams"]
   spec.email         = ["g@rethada.ms"]
 
-  spec.summary       = %q{A Ruby FFI wrapper around the System11 hidapi C library}
-  spec.description   = %q{}
+  spec.summary       = "A Ruby FFI wrapper around the System11 hidapi C library"
+  spec.description   = ""
   spec.homepage      = "https://github.com/gareth/ruby_hid_api"
 
-  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]

lib/hid_api.rb

@@ -1,16 +1,18 @@
-require 'ffi'
+require "ffi"
 
+# A Ruby wrapper around the C `hidapi` library
 module HidApi
   class HidError < StandardError; end
 
   extend FFI::Library
-  ffi_lib 'hidapi'
+  ffi_lib "hidapi"
 
-  autoload :Device,     'hid_api/device'
-  autoload :DeviceInfo, 'hid_api/device_info'
-  autoload :Util,       'hid_api/util'
-  autoload :VERSION,    'hid_api/version'
-  autoload :WideString, 'hid_api/wide_string'
+  autoload :Deprecated, "hid_api/deprecated"
+  autoload :Device,     "hid_api/device"
+  autoload :DeviceInfo, "hid_api/device_info"
+  autoload :Util,       "hid_api/util"
+  autoload :VERSION,    "hid_api/version"
+  autoload :WideString, "hid_api/wide_string"
 
   typedef DeviceInfo.auto_ptr, :hid_device_info
   typedef WideString, :wide_string
@@ -46,13 +48,19 @@ class << self
     alias exit hid_exit
     alias enumerate hid_enumerate
     alias free_enumeration hid_free_enumeration
-    def open vendor_id, product_id, serial_number=nil
+    def open(vendor_id, product_id, serial_number = nil)
       device = hid_open(vendor_id, product_id, serial_number || 0)
-      raise HidError, "Unable to open #{[vendor_id, product_id, serial_number].inspect}" if device.null?
+      if device.null?
+        error = format(
+          "Unable to open %s",
+          [vendor_id, product_id, serial_number].inspect
+        )
+        raise HidError, error
+      end
       device
     end
 
-    def open_path path
+    def open_path(path)
       device = hid_open_path(path)
       raise HidError, "Unable to open #{path.inspect}" if device.null?
       device
@@ -61,4 +69,4 @@ def open_path path
 end
 
 # Attempts to extend some core FFI classes with platform-aware string-handling
-FFI::AbstractMemory.include(HidApi::Util::WCHAR)
+FFI::AbstractMemory.include(HidApi::Util::WCHAR)

lib/hid_api/deprecated.rb

@@ -0,0 +1,36 @@
+module HidApi
+  # Adds the ability to mark some methods as deprecated.
+  #
+  # Uses the approach listed at
+  # http://seejohncode.com/2012/01/09/deprecating-methods-in-ruby/
+  module Deprecated
+    # Define a deprecated alias for a method
+    # @param [Symbol] name - name of method to define
+    # @param [Symbol] replacement - name of method to (alias)
+    def deprecated_alias(name, replacement)
+      # Create a wrapped version
+      define_method(name) do |*args, &block|
+        warn "##{name} deprecated (please use ##{replacement})"
+        send replacement, *args, &block
+      end
+    end
+
+    # Deprecate a defined method
+    # @param [Symbol] name - name of deprecated method
+    # @param [Symbol] replacement - name of the desired replacement
+    def deprecated(name, replacement = nil)
+      # Replace old method
+      old_name = :"#{name}_without_deprecation"
+      alias_method old_name, name
+      # And replace it with a wrapped version
+      define_method(name) do |*args, &block|
+        if replacement
+          warn "##{name} deprecated (please use ##{replacement})"
+        else
+          warn "##{name} deprecated"
+        end
+        send old_name, *args, &block
+      end
+    end
+  end
+end

lib/hid_api/device.rb

@@ -1,33 +1,39 @@
-require 'ffi'
+require "ffi"
 
 module HidApi
+  # An FFI pointer extended to expose HID device functionality
   class Device < FFI::Pointer
+    extend Deprecated
     extend FFI::DataConverter
     native_type FFI::Type::POINTER
 
-    def self.from_native(value, ctx)
+    def self.from_native(value, _ctx)
       new(value)
     end
 
     def close
       HidApi.hid_close(self)
     end
 
-    def set_nonblocking(int)
+    def nonblocking=(int)
       HidApi.hid_set_nonblocking self, int
     end
+    deprecated_alias :set_nonblocking, :nonblocking=
 
-    def get_manufacturer_string
+    def manufacturer_string
       get_buffered_string :manufacturer
     end
+    deprecated_alias :get_manufacturer_string, :manufacturer_string
 
-    def get_product_string
+    def product_string
       get_buffered_string :product
     end
+    deprecated_alias :get_product_string, :product_string
 
-    def get_serial_number_string
+    def serial_number_string
       get_buffered_string :serial_number
     end
+    deprecated_alias :get_serial_number_string, :serial_number_string
 
     def read(length)
       buffer = clear_buffer length
@@ -57,11 +63,11 @@ def write(data)
       end
     end
 
-    def get_feature_report(data)
+    def get_feature_report(_data)
       raise NotImplementedError
     end
 
-    def send_feature_report(data)
+    def send_feature_report(_data)
       raise NotImplementedError
     end
 
@@ -72,14 +78,15 @@ def error
     end
 
     private
-    def clear_buffer length
+
+    def clear_buffer(length)
       b = FFI::Buffer.new(1, length)
       # FFI::Buffer doesn't clear the first byte if length < 8
       b.put_char 0, 0
       b
     end
 
-    def get_buffered_string field
+    def get_buffered_string(field)
       buffer = clear_buffer 255
       HidApi.send "hid_get_#{field}_string", self, buffer, buffer.length
       buffer.read_wchar_string

lib/hid_api/device_info.rb

@@ -1,4 +1,4 @@
-require 'ffi'
+require "ffi"
 
 module HidApi
   # Represents the hid_device_info struct returned as part of
@@ -36,7 +36,7 @@ def self.release(pointer)
 
     def inspect
       product_string.tap do |s|
-        s << " (%s)" % path unless path.empty?
+        s << format(" (%s)", path) unless path.empty?
       end
     end
 
@@ -52,4 +52,4 @@ def each
       end
     end
   end
-end
+end

lib/hid_api/util.rb

@@ -1,5 +1,5 @@
 module HidApi
-  module Util
-    autoload :WCHAR, 'hid_api/util/wchar'
+  module Util # :nodoc:
+    autoload :WCHAR, "hid_api/util/wchar"
   end
-end
+end

lib/hid_api/util/wchar.rb

@@ -1,21 +1,29 @@
 module HidApi
   module Util
+    # A utility module that provides simple (maybe naive) platform-dependent
+    # support for wide characters
     module WCHAR
-      WCHAR_T_WIDTH = RUBY_PLATFORM =~ /mswin/i ? 2 : 4
+      WCHAR_T_WIDTH = ::RUBY_PLATFORM =~ /mswin/i ? 2 : 4
 
       # Maps a WCHAR_T_WIDTH to the corresponding Array#pack character width
       FORMATS = {
-        2 => 'S',
-        4 => 'L'
-      }
+        2 => "S",
+        4 => "L"
+      }.freeze
+
+      # The platform-specific Array#pack format for wide characters
+      FORMAT = FORMATS[WCHAR_T_WIDTH].freeze
 
       # Maps a WCHAR_T_WIDTH to the corresponding string encoding
-      ENCODINGS = {
-        2 => 'utf-16le',
-        4 => 'utf-32le'
-      }
+      ENCODING = {
+        2 => "utf-16le",
+        4 => "utf-32le"
+      }.freeze
+
+      # The platform-specific String encoding that can handle wide characters
+      ENCODING = ENCODINGS[WCHAR_T_WIDTH].freeze
 
-      def read_wchar_string max_chars=nil
+      def read_wchar_string(_max_chars = nil)
         buffer = []
         offset = 0
         loop do
@@ -25,8 +33,8 @@ def read_wchar_string max_chars=nil
           buffer << char
           offset += 1
         end
-        buffer.pack("#{FORMATS[WCHAR_T_WIDTH]}*").force_encoding(ENCODINGS[WCHAR_T_WIDTH]).encode('utf-8')
+        buffer.pack("#{FORMAT}*").force_encoding(ENCODING).encode("utf-8")
       end
     end
   end
-end
+end