Change LibraryPath.new to keyword arguments and add documentation

Because abi_number and root aren't self descriptive.

lib/ffi/library.rb

@@ -33,7 +33,7 @@
 module FFI
   CURRENT_PROCESS = USE_THIS_PROCESS_AS_LIBRARY = FFI.make_shareable(Object.new)
 
-  # @param [#to_s] lib library name
+  # @param [String, FFI::LibraryPath] lib library name or LibraryPath object
   # @return [String] library name formatted for current platform
   # Transform a generic library name to a platform library name
   # @example
@@ -43,9 +43,9 @@ module FFI
   #  # Windows
   #  FFI.map_library_name 'c'     # -> "msvcrt.dll"
   #  FFI.map_library_name 'jpeg'  # -> "jpeg.dll"
-  def self.map_library_name(value)
+  def self.map_library_name(lib)
     # Mangle the library name to reflect the native library naming conventions
-    LibraryPath.wrap(value).to_s
+    LibraryPath.wrap(lib).to_s
   end
 
   # Exception raised when a function is not found in libraries

lib/ffi/library_path.rb

@@ -29,7 +29,36 @@
 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.#
 
 module FFI
-  class LibraryPath < ::Struct.new(:name, :abi_number, :root)
+  # Transform a generic library name and ABI number to a platform library name
+  #
+  # Example:
+  #   module LibVips
+  #     extend FFI::Library
+  #     ffi_lib LibraryPath.new("vips", abi_number: 42)
+  #   end
+  #
+  # This translates to the following library file names:
+  #   libvips-42.dll    on Windows
+  #   libvips.so.42     on Linux
+  #   libvips.42.dylib  on Macos
+  #
+  # See https://packaging.ubuntu.com/html/libraries.html for more information about library naming.
+  class LibraryPath
+    attr_reader :name
+    attr_reader :abi_number
+    attr_reader :root
+
+    # Build a new library path
+    #
+    # * <tt>name</tt> :  The name of the library without file prefix or suffix.
+    # * <tt>abi_number</tt> :  The ABI number of the library.
+    # * <tt>root</tt> :  An optional base path prepended to the library name.
+    def initialize(name, abi_number: nil, root: nil)
+      @name = name
+      @abi_number = abi_number
+      @root = root
+    end
+
     def self.wrap(value)
       # We allow instances of LibraryPath to pass through transparently:
       return value if value.is_a?(self)
@@ -57,12 +86,12 @@ def full_name
           "#{Platform::LIBPREFIX}#{name}.#{Platform::LIBSUFFIX}.#{abi_number}"
         end
       else
-        # Otherwise we just use a generic format:
+        # Otherwise we just add prefix and suffix:
         lib = name
         # Add library prefix if missing
         lib = Platform::LIBPREFIX + lib unless lib =~ /^#{Platform::LIBPREFIX}/
         # Add library extension if missing
-        r = Platform::IS_WINDOWS || Platform::IS_MAC ? "\\.#{Platform::LIBSUFFIX}$" : "\\.so($|\\.[1234567890]+)"
+        r = Platform.windows? || Platform.mac? ? "\\.#{Platform::LIBSUFFIX}$" : "\\.so($|\\.[1234567890]+)"
         lib += ".#{Platform::LIBSUFFIX}" unless lib =~ /#{r}/
         lib
       end

spec/ffi/ffi_spec.rb

@@ -39,13 +39,13 @@
     end
 
     it "should return library path with abi version" do
-      expect(FFI.map_library_name(FFI::LibraryPath.new('vips', 42))).to be =~ /#{prefix}vips.*42/
+      expect(FFI.map_library_name(FFI::LibraryPath.new('vips', abi_number: 42))).to be =~ /#{prefix}vips.*42/
     end
 
     it "should return library path with root" do
       root = "/non/existant/root"
 
-      expect(FFI.map_library_name(FFI::LibraryPath.new('vips', 42, root))).to be =~ /#{root}/#{prefix}vips.*42/
+      expect(FFI.map_library_name(FFI::LibraryPath.new('vips', abi_number: 42, root: root))).to be =~ /#{root}/#{prefix}vips.*42/
     end
   end