ffi 1.0.9 → 1.0.10

data/ext/ffi_c/libffi.gnu.mk

@@ -5,7 +5,7 @@
 
 
 # Tack the extra deps onto the autogenerated variables
-INCFLAGS += -I$(LIBFFI_BUILD_DIR)/include
+INCFLAGS += -I"$(LIBFFI_BUILD_DIR)"/include
 LOCAL_LIBS += $(LIBFFI)
 BUILD_DIR = $(shell pwd)
 LIBFFI_CFLAGS = $(FFI_MMAP_EXEC)
@@ -17,8 +17,8 @@ else
   LIBFFI_SRC_DIR := $(abspath $(srcdir)/libffi)
 endif
 
-LIBFFI = $(LIBFFI_BUILD_DIR)/.libs/libffi_convenience.a
-LIBFFI_CONFIGURE = $(LIBFFI_SRC_DIR)/configure --disable-static \
+LIBFFI = "$(LIBFFI_BUILD_DIR)"/.libs/libffi_convenience.a
+LIBFFI_CONFIGURE = "$(LIBFFI_SRC_DIR)"/configure --disable-static \
 	--with-pic=yes --disable-dependency-tracking
 
 $(OBJS):	$(LIBFFI)

data/ext/ffi_c/libffi.mk

@@ -3,11 +3,11 @@
 include ${srcdir}/libffi.gnu.mk
 
 $(LIBFFI):		
-	@mkdir -p $(LIBFFI_BUILD_DIR)
-	@if [ ! -f $(LIBFFI_BUILD_DIR)/Makefile ]; then \
+	@mkdir -p "$(LIBFFI_BUILD_DIR)"
+	@if [ ! -f "$(LIBFFI_BUILD_DIR)"/Makefile ]; then \
 	    echo "Configuring libffi"; \
-	    cd $(LIBFFI_BUILD_DIR) && \
+	    cd "$(LIBFFI_BUILD_DIR)" && \
 		/usr/bin/env CFLAGS="$(LIBFFI_CFLAGS)" \
 		/bin/sh $(LIBFFI_CONFIGURE) $(LIBFFI_HOST) > /dev/null; \
 	fi
-	cd $(LIBFFI_BUILD_DIR) && $(MAKE)
+	$(MAKE) -C "$(LIBFFI_BUILD_DIR)"

data/lib/ffi.rb

@@ -1,11 +1,15 @@
-begin
-  if RUBY_VERSION =~ /1.8/
-    require '1.8/ffi_c'
-  elsif RUBY_VERSION =~ /1.9/
-    require '1.9/ffi_c'
+if !defined?(RUBY_ENGINE) || RUBY_ENGINE == "ruby"
+  begin
+    if RUBY_VERSION =~ /1.8/
+      require '1.8/ffi_c'
+    elsif RUBY_VERSION =~ /1.9/
+      require '1.9/ffi_c'
+    else
+      require 'ffi_c'
+    end
+  rescue Exception
+    require 'ffi_c'
   end
-rescue Exception
-  require 'ffi_c'
-end
 
-require 'ffi/ffi'
+  require 'ffi/ffi'
+end

data/lib/ffi/autopointer.rb

@@ -23,17 +23,31 @@ module FFI
   class AutoPointer < Pointer
     extend DataConverter
 
-    # call-seq:
-    #   AutoPointer.new(pointer, method)     => the passed Method will be invoked at GC time
-    #   AutoPointer.new(pointer, proc)       => the passed Proc will be invoked at GC time (SEE WARNING BELOW!)
-    #   AutoPointer.new(pointer) { |p| ... } => the passed block will be invoked at GC time (SEE WARNING BELOW!)
-    #   AutoPointer.new(pointer)             => the pointer's release() class method will be invoked at GC time
+    # @overload initialize(pointer, method)
+    #  @param [Pointer] pointer
+    #  @param [Method] method
+    #  @return [self]
+    #  The passed Method will be invoked at GC time.
+    # @overload initialize(pointer, proc)
+    #  @param [Pointer] pointer
+    #  @return [self]
+    #  The passed Proc will be invoked at GC time (SEE WARNING BELOW!)
+    #  @note WARNING: passing a proc _may_ cause your pointer to never be GC'd, unless you're 
+    #   careful to avoid trapping a reference to the pointer in the proc. See the test 
+    #   specs for examples.
+    # @overload initialize(pointer) { |p| ... }
+    #  @param [Pointer] pointer
+    #  @yieldparam [Pointer] p +pointer+ passed to the block
+    #  @return [self]
+    #  The passed block will be invoked at GC time.
+    #  @note WARNING: passing a block will cause your pointer to never be GC'd. This is bad.
+    # @overload initialize(pointer)
+    #  @param [Pointer] pointer
+    #  @return [self]
+    #  The pointer's release() class method will be invoked at GC time.
     #
-    # WARNING: passing a proc _may_ cause your pointer to never be GC'd, unless you're careful to avoid trapping a reference to the pointer in the proc. See the test specs for examples.
-    # WARNING: passing a block will cause your pointer to never be GC'd. This is bad.
-    #
-    # Please note that the safest, and therefore preferred, calling
-    # idiom is to pass a Method as the second parameter. Example usage:
+    # @note The safest, and therefore preferred, calling
+    #  idiom is to pass a Method as the second parameter. Example usage:
     #
     #   class PointerHelper
     #     def self.release(pointer)
@@ -43,12 +57,12 @@ module FFI
     #
     #   p = AutoPointer.new(other_pointer, PointerHelper.method(:release))
     #
-    # The above code will cause PointerHelper#release to be invoked at GC time.
-    #
-    # The last calling idiom (only one parameter) is generally only
-    # going to be useful if you subclass AutoPointer, and override
-    # release(), which by default does nothing.
+    #  The above code will cause PointerHelper#release to be invoked at GC time.
     #
+    # @note
+    #  The last calling idiom (only one parameter) is generally only
+    #  going to be useful if you subclass {AutoPointer}, and override
+    #  #release, which by default does nothing.
     def initialize(ptr, proc=nil, &block)
       super(ptr)
       raise TypeError, "Invalid pointer" if ptr.nil? || !ptr.kind_of?(Pointer) \
@@ -67,52 +81,100 @@ module FFI
       self
     end
 
+    # @return [nil]
+    # Free the pointer.
     def free
       @releaser.free
     end
 
+    # @param [Boolean] autorelease
+    # @return [Boolean] +autorelease+
+    # Set +autorelease+ property. See {Pointer Autorelease section at Pointer}.
     def autorelease=(autorelease)
       @releaser.autorelease=(autorelease)
     end
 
+    # @abstract Base class for {AutoPointer}'s releasers.
+    #  
+    #  All subclasses of Releaser should define a +#release(ptr)+ method.
+    # A releaser is an object in charge of release an {AutoPointer}.
     class Releaser
+      # @param [Pointer] ptr
+      # @param [#call] proc
+      # @return [nil]
+      # A new instance of Releaser.
       def initialize(ptr, proc)
         @ptr = ptr
         @proc = proc
         @autorelease = true
       end
 
+      # @return [nil]
+      # Free pointer.
       def free
-        raise RuntimeError.new("pointer already freed") unless @ptr
-        @autorelease = false
-        @ptr = nil
-        @proc = nil
+        if @ptr
+          release(@ptr)
+          @autorelease = false
+          @ptr = nil
+          @proc = nil
+        end
       end
       
+      # @param [Boolean] autorelease
+      # @return [Boolean] autorelease
+      # Set +autorelease+ attribute for pointer managed by Releaser.
       def autorelease=(autorelease)
-        raise RuntimeError.new("pointer already freed") unless @ptr
-        @autorelease = autorelease
+        @autorelease = autorelease if @ptr
       end
-
+      
+      # @param args
+      # Release pointer if +autorelease+ is set.
+      def call(*args)
+        release(@ptr) if @autorelease && @ptr
+      end
+      
     end
 
+    # DefaultReleaser is a {Releaser} used when an {AutoPointer} is defined without Proc
+    # or Method. In this case, the pointer to release must be of a class derived from 
+    # AutoPointer with a +#release+ class method.
     class DefaultReleaser < Releaser
-      def call(*args)
-        @proc.release(@ptr) if @autorelease && @ptr
+      # @param [Pointer] ptr
+      # @return [nil]
+      # Release +ptr+ by using his #release class method.
+      def release(ptr)
+        @proc.release(ptr)
       end
     end
 
+    # CallableReleaser is a {Releaser} used when an {AutoPointer} is defined with a
+    # Proc or a Method.
     class CallableReleaser < Releaser
-      def call(*args)
-        @proc.call(@ptr) if @autorelease && @ptr
+      # @param [Pointer] ptr
+      # @return [nil]
+      # Release +ptr+ by using Proc or Method defined at +ptr+ {AutoPointer#initialize initialization}.
+      def release(ptr)
+        @proc.call(ptr)
       end
     end
 
+    # Return native type of AutoPointer.
+    #
+    # Override {DataConverter#native_type}.
+    # @return [Type::POINTER]
+    # @raise {RuntimeError} if class does not implement a +#release+ method
     def self.native_type
       raise RuntimeError.new("no release method defined for #{self.inspect}") unless self.respond_to?(:release)
       Type::POINTER
     end
 
+    # Create a new AutoPointer.
+    #
+    # Override {DataConverter#from_native}.
+    # @overload self.from_native(ptr, ctx)
+    # @param [Pointer] ptr 
+    # @param ctx not used. Please set +nil+.
+    # @return [AutoPointer]
     def self.from_native(val, ctx)
       self.new(val)
     end

data/lib/ffi/enum.rb

@@ -21,20 +21,27 @@
 
 module FFI
 
+  # An instance of this class permits to manage {Enum}s. In fact, Enums is a collection of {Enum}s.
   class Enums
 
+    # @return [nil]
     def initialize
       @all_enums = Array.new
       @tagged_enums = Hash.new
       @symbol_map = Hash.new
     end
 
+    # @param [Enum] enum
+    # Add an {Enum} to the collection.
     def <<(enum)
       @all_enums << enum
       @tagged_enums[enum.tag] = enum unless enum.tag.nil?
       @symbol_map.merge!(enum.symbol_map)
     end
 
+    # @param query enum tag or part of an enum name
+    # @return [Enum]
+    # Find a {Enum} in collection.
     def find(query)
       if @tagged_enums.has_key?(query)
         @tagged_enums[query]
@@ -43,17 +50,33 @@ module FFI
       end
     end
 
+    # @param symbol a symbol to find in merge symbol maps of all enums.
+    # @return a symbol
     def __map_symbol(symbol)
       @symbol_map[symbol]
     end
 
   end
 
+  # Represents a C enum.
+  #
+  # For a C enum:
+  #  enum fruits {
+  #    apple,
+  #    banana,
+  #    orange,
+  #    pineapple
+  #  };
+  # are defined this vocabulary:
+  # * a _symbol_ is a word from the enumeration (ie. _apple_, by example);
+  # * a _value_ is the value of a symbol in the enumeration (by example, apple has value _0_ and banana _1_).
   class Enum
     include DataConverter
 
     attr_reader :tag
 
+    # @param [nil, Enumerable] info
+    # @param tag enum tag
     def initialize(info, tag=nil)
       @tag = tag
       @kv_map = Hash.new
@@ -75,10 +98,20 @@ module FFI
       @vk_map = Hash[@kv_map.map{|k,v| [v,k]}]
     end
 
+    # @return [Array] enum symbol names
     def symbols
       @kv_map.keys
     end
 
+    # Get a symbol or a value from the enum.
+    # @overload [](query)
+    #  Get enum value from symbol.
+    #  @param [Symbol] query
+    #  @return [Integer]
+    # @overload [](query)
+    #  Get enum symbol from value.
+    #  @param [Integer] query
+    #  @return [Symbol]
     def [](query)
       case query
       when Symbol
@@ -89,6 +122,8 @@ module FFI
     end
     alias find []
 
+    # Get the symbol map.
+    # @return [Hash]
     def symbol_map
       @kv_map
     end
@@ -96,10 +131,15 @@ module FFI
     alias to_h symbol_map
     alias to_hash symbol_map
 
+    # Get native type of Enum
+    # @return [Type::INT]
     def native_type
       Type::INT
     end
 
+    # @param [Symbol, Integer, #to_int] val
+    # @param ctx unused
+    # @return [Integer] value of a enum symbol
     def to_native(val, ctx)
       @kv_map[val] || if val.is_a?(Integer)
         val
@@ -110,6 +150,8 @@ module FFI
       end
     end
 
+    # @param val
+    # @return symbol name if it exists for +val+.
     def from_native(val, ctx)
       @vk_map[val] || val
     end

data/lib/ffi/errno.rb

@@ -19,10 +19,15 @@
 #
 
 module FFI
+  # @return (see FFI::LastError.error)
+  # @see FFI::LastError.error
   def self.errno
     FFI::LastError.error
   end
+  # @param error (see FFI::LastError.error=)
+  # @return (see FFI::LastError.error=)
+  # @see FFI::LastError.error=
   def self.errno=(error)
     FFI::LastError.error = error
   end
-end
+end

data/lib/ffi/ffi.rb

@@ -21,6 +21,7 @@ require 'ffi/platform'
 require 'ffi/types'
 require 'ffi/library'
 require 'ffi/errno'
+require 'ffi/pointer'
 require 'ffi/memorypointer'
 require 'ffi/struct'
 require 'ffi/union'

data/lib/ffi/io.rb

@@ -19,15 +19,26 @@
 #
 
 module FFI
+  
+  # This module implements a couple of class methods to play with IO.
   module IO
+    # @param [Integer] fd file decriptor
+    # @param [String] mode mode string
+    # @return [::IO]
+    # Synonym for IO::for_fd.
     def self.for_fd(fd, mode = "r")
       ::IO.for_fd(fd, mode)
     end
 
+    # @param [#read] io io to read from
+    # @param [AbstractMemory] buf destination for data read from +io+
+    # @param [nil, Numeric] len maximul number of bytes to read from +io+. If +nil+, 
+    #  read until end of file.
+    # @return [Numeric] length really read, in bytes
     #
-    # A version of IO#read that reads into a native buffer
+    # A version of IO#read that reads data from an IO and put then into a native buffer.
     # 
-    # This will be optimized at some future time to eliminate the double copy
+    # This will be optimized at some future time to eliminate the double copy.
     #
     def self.native_read(io, buf, len)
       tmp = io.read(len)

data/lib/ffi/library.rb

@@ -21,6 +21,16 @@
 module FFI
   CURRENT_PROCESS = USE_THIS_PROCESS_AS_LIBRARY = Object.new
 
+  # @param [#to_s] lib library name
+  # @return [String] library name formatted for current platform
+  # Transform a generic library name to a platform library name
+  # @example
+  #  # Linux
+  #  FFI.map_library_name 'c'     # -> "libc.so.6"
+  #  FFI.map_library_name 'jpeg'  # -> "libjpeg.so"
+  #  # Windows
+  #  FFI.map_library_name 'c'     # -> "msvcrt.dll"
+  #  FFI.map_library_name 'jpeg'  # -> "jpeg.dll"
   def self.map_library_name(lib)
     # Mangle the library name to reflect the native library naming conventions
     lib = lib.to_s unless lib.kind_of?(String)
@@ -28,27 +38,51 @@ module FFI
 
     if lib && File.basename(lib) == lib
       lib = Platform::LIBPREFIX + lib unless lib =~ /^#{Platform::LIBPREFIX}/
-      r = Platform::IS_LINUX ? "\\.so($|\\.[1234567890]+)" : "\\.#{Platform::LIBSUFFIX}$"
+      r = Platform::IS_GNU ? "\\.so($|\\.[1234567890]+)" : "\\.#{Platform::LIBSUFFIX}$"
       lib += ".#{Platform::LIBSUFFIX}" unless lib =~ /#{r}/
     end
 
     lib
   end
 
+  # Exception raised when a function is not found in libraries
   class NotFoundError < LoadError
     def initialize(function, *libraries)
       super("Function '#{function}' not found in [#{libraries[0].nil? ? 'current process' : libraries.join(", ")}]")
     end
   end
 
+  # This module is the base to use native functions.
+  #
+  # A basic usage may be:
+  #  require 'ffi'
+  #  
+  #  module Hello
+  #    extend FFI::Library
+  #    ffi_lib FFI::Library::LIBC
+  #    attach_function 'puts', [ :string ], :int
+  #  end
+  #  
+  #  Hello.puts("Hello, World")
+  #
+  # 
   module Library
     CURRENT_PROCESS = FFI::CURRENT_PROCESS
     LIBC = FFI::Platform::LIBC
 
+    # @param mod extended object
+    # @return [nil]
+    # @raise {RuntimeError} if +mod+ is not a Module
+    # Test if extended object is a Module. If not, raise RuntimeError.
     def self.extended(mod)
       raise RuntimeError.new("must only be extended by module") unless mod.kind_of?(Module)
     end
 
+    
+    # @param [Array] names names of libraries to load
+    # @return [Array<DynamicLibrary>]
+    # @raise {LoadError} if a library cannot be opened
+    # Load native libraries.
     def ffi_lib(*names)
       lib_flags = defined?(@ffi_lib_flags) ? @ffi_lib_flags : FFI::DynamicLibrary::RTLD_LAZY | FFI::DynamicLibrary::RTLD_LOCAL
       ffi_libs = names.map do |name|
@@ -67,12 +101,24 @@ module FFI
               break if lib
 
             rescue Exception => ex
-              errors[libname] = ex
+              ldscript = false
+              if ex.message =~ /(([^ \t()])+\.so([^ \t:()])*):([ \t])*invalid ELF header/
+                if File.read($1) =~ /GROUP *\( *([^ \)]+) *\)/
+                  libname = $1
+                  ldscript = true
+                end
+              end
+
+              if ldscript
+                retry
+              else
+                errors[libname] = ex
+              end
             end
           end
 
           if lib.nil?
-            raise LoadError.new(errors.values.join('. '))
+            raise LoadError.new(errors.values.join(".\n"))
           end
 
           # return the found lib
@@ -83,17 +129,30 @@ module FFI
       @ffi_libs = ffi_libs
     end
 
-
+    # Set the calling convention for {#attach_function} and {#callback}
+    #
+    # @see http://en.wikipedia.org/wiki/Stdcall#stdcall
+    # @note +:stdcall+ is typically used for attaching Windows API functions
+    #
+    # @param [Symbol] convention one of +:default+, +:stdcall+
+    # @return [Symbol] the new calling convention
     def ffi_convention(convention)
       @ffi_convention = convention
     end
 
-
+    # @see #ffi_lib
+    # @return [Array<FFI::DynamicLibrary>] array of currently loaded FFI libraries
+    # @raise [LoadError] if no libraries have been loaded (using {#ffi_lib})
+    # Get FFI libraries loaded using {#ffi_lib}.
     def ffi_libraries
       raise LoadError.new("no library specified") if !defined?(@ffi_libs) || @ffi_libs.empty?
       @ffi_libs
     end
 
+    # Flags used in {#ffi_lib}.
+    #
+    # This map allows you to supply symbols to {#ffi_lib_flags} instead of
+    # the actual constants.
     FlagsMap = {
       :global => DynamicLibrary::RTLD_GLOBAL,
       :local => DynamicLibrary::RTLD_LOCAL,
@@ -101,15 +160,53 @@ module FFI
       :now => DynamicLibrary::RTLD_NOW
     }
 
+    # Sets library flags for {#ffi_lib}.
+    #
+    # @example
+    #   ffi_lib_flags(:lazy, :local) # => 5
+    #
+    # @param [Symbol, …] flags (see {FlagsMap})
+    # @return [Fixnum] the new value
     def ffi_lib_flags(*flags)
       @ffi_lib_flags = flags.inject(0) { |result, f| result | FlagsMap[f] }
     end
 
-    
+
     ##
-    # Attach C function to this module.
+    # @overload attach_function(func, args, returns, options = {})
+    #  @example attach function without an explicit name
+    #    module Foo
+    #      extend FFI::Library
+    #      ffi_lib FFI::Library::LIBC
+    #      attach_function :malloc, [:size_t], :pointer
+    #    end
+    #    # now callable via Foo.malloc
+    # @overload attach_function(name, func, args, returns, options = {})
+    #  @example attach function with an explicit name
+    #    module Bar
+    #      extend FFI::Library
+    #      ffi_lib FFI::Library::LIBC
+    #      attach_function :c_malloc, :malloc, [:size_t], :pointer
+    #    end
+    #    # now callable via Bar.c_malloc
+    #
+    # Attach C function +func+ to this module.
+    #
     #
-    def attach_function(mname, a2, a3, a4=nil, a5 = nil)
+    # @param [#to_s] name name of ruby method to attach as
+    # @param [#to_s] func name of C function to attach
+    # @param [Array<Symbol>] args an array of types
+    # @param [Symbol] returns type of return value
+    # @option options [Boolean] :blocking (@blocking) set to true if the C function is a blocking call
+    # @option options [Symbol] :convention (:default) calling convention (see {#ffi_convention})
+    # @option options [FFI::Enums] :enums
+    # @option options [Hash] :type_map
+    #
+    # @return [FFI::VariadicInvoker]
+    #
+    # @raise [FFI::NotFoundError] if +func+ cannot be found in the attached libraries (see {#ffi_lib})
+    def attach_function(name, func, args, returns = nil, options = nil)
+      mname, a2, a3, a4, a5 = name, func, args, returns, options
       cname, arg_types, ret_type, opts = (a4 && (a2.is_a?(String) || a2.is_a?(Symbol))) ? [ a2, a3, a4, a5 ] : [ mname.to_s, a2, a3, a4 ]
 
       # Convert :foo to the native type
@@ -120,7 +217,7 @@ module FFI
         :blocking => defined?(@blocking) && @blocking,
         :enums => defined?(@ffi_enums) ? @ffi_enums : nil,
       }
-      
+
       @blocking = false
       options.merge!(opts) if opts && opts.is_a?(Hash)
 
@@ -129,7 +226,10 @@ module FFI
       ffi_libraries.each do |lib|
         if invokers.empty?
           begin
-            function = lib.find_function(cname.to_s)
+            function = nil
+            function_names(cname, arg_types).find do |name|
+              function = lib.find_function(name)
+            end
             raise LoadError unless function
 
             invokers << if arg_types.length > 0 && arg_types[arg_types.length - 1] == FFI::NativeType::VARARGS
@@ -150,7 +250,56 @@ module FFI
       invoker
     end
 
+    # @param [#to_s] name function name
+    # @param [Array] arg_types function's argument types
+    # @return [Array<String>]
+    # This function returns a list of possible names to lookup.
+    # @note Function names on windows may be decorated if they are using stdcall. See
+    #   * http://en.wikipedia.org/wiki/Name_mangling#C_name_decoration_in_Microsoft_Windows
+    #   * http://msdn.microsoft.com/en-us/library/zxk0tw93%28v=VS.100%29.aspx
+    #   * http://en.wikibooks.org/wiki/X86_Disassembly/Calling_Conventions#STDCALL
+    #   Note that decorated names can be overridden via def files.  Also note that the
+    #   windows api, although using, doesn't have decorated names.
+    def function_names(name, arg_types)
+      result = [name.to_s]
+      if @ffi_convention == :stdcall
+        # Get the size of each parameter
+        size = arg_types.inject(0) do |mem, arg|
+          mem + arg.size
+        end
+
+        # Next, the size must be a multiple of 4
+        size += (4 - size) % 4
+
+        result << "_#{name.to_s}@#{size}" # win32
+        result << "#{name.to_s}@#{size}" # win64
+      end
+      result
+    end
 
+    # @overload attach_variable(mname, cname, type)
+    #  @example
+    #   module Bar
+    #     extend FFI::Library
+    #     ffi_lib 'my_lib'
+    #     attach_variable :c_myvar, :myvar, :long
+    #   end
+    #   # now callable via Bar.c_myvar
+    # @overload attach_variable(cname, type)
+    #  @example
+    #   module Bar
+    #     extend FFI::Library
+    #     ffi_lib 'my_lib'
+    #     attach_variable :myvar, :long
+    #   end
+    #   # now callable via Bar.myvar
+    # @param [#to_s] mname name of ruby method to attach as
+    # @param [#to_s] cname name of C variable to attach
+    # @param [DataConverter, Struct, Symbol, Type] type C varaible's type
+    # @return [DynamicLibrary::Symbol]
+    # @raise {FFI::NotFoundError} if +cname+ cannot be found in libraries
+    #
+    # Attach C variable +cname+ to this module.
     def attach_variable(mname, a1, a2 = nil)
       cname, type = a2 ? [ a1, a2 ] : [ mname.to_s, a1 ]
       address = nil
@@ -171,7 +320,7 @@ module FFI
           def self.#{mname}
             @@ffi_gvar_#{mname}
           end
-        code
+code
 
       else
         sc = Class.new(FFI::Struct)
@@ -195,6 +344,13 @@ module FFI
       address
     end
 
+
+    # @overload callback(name, params, ret)
+    # @overload callback(params, ret)
+    # @param name callback name to add to type map
+    # @param [Array] params array of parameters' types
+    # @param [DataConverter, Struct, Symbol, Type] ret callback return type
+    # @return [FFI::CallbackInfo]
     def callback(*args)
       raise ArgumentError, "wrong number of arguments" if args.length < 2 || args.length > 3
       name, params, ret = if args.length == 3
@@ -216,6 +372,22 @@ module FFI
       cb
     end
 
+    # @param [DataConverter, Symbol, Type] old
+    # @param  add
+    # @param [] info
+    # @return [FFI::Enum, FFI::Type]
+    # Register or get an already registered type definition.
+    #
+    # To register a new type definition, +old+ should be a {FFI::Type}. +add+
+    # is in this case the type definition.
+    #
+    # If +old+ is a {DataConverter}, a {Type::Mapped} is returned.
+    #
+    # If +old+ is +:enum+
+    # * and +add+ is an +Array+, a call to {#enum} is made with +add+ as single parameter;
+    # * in others cases, +info+ is used to create a named enum.
+    #
+    # If +old+ is a key for type map, #typedef get +old+ type definition.
     def typedef(old, add, info=nil)
       @ffi_typedefs = Hash.new unless defined?(@ffi_typedefs)
 
@@ -240,13 +412,25 @@ module FFI
       end
     end
 
+    # @overload enum(name, values)
+    #  Create a named enum.
+    #  @example
+    #   enum :foo, [:zero, :one, :two]  # named enum
+    #  @param [Symbol] name name for new enum
+    #  @param [Array] values values for enum
+    # @overload enum(*args)
+    #  Create an unnamed enum.
+    #  @example
+    #   enum :zero, :one, :two  # unnamed enum
+    #  @param args values for enum
+    # @overload enum(values)
+    #  Create an unnamed enum.
+    #  @example
+    #   enum [:zero, :one, :two]  # unnamed enum, equivalent to above example
+    #  @param [Array] values values for enum
+    # @return [FFI::Enum]
+    # Create a new {FFI::Enum}.
     def enum(*args)
-      #
-      # enum can be called as:
-      # enum :zero, :one, :two  # unnamed enum
-      # enum [ :zero, :one, :two ] # equivalent to above
-      # enum :foo, [ :zero, :one, :two ] create an enum named :foo
-      #
       name, values = if args[0].kind_of?(Symbol) && args[1].kind_of?(Array)
         [ args[0], args[1] ]
       elsif args[0].kind_of?(Array)
@@ -262,18 +446,27 @@ module FFI
       e
     end
 
+    # @param name
+    # @return [FFI::Enum]
+    # Find an enum by name.
     def enum_type(name)
       @ffi_enums.find(name) if defined?(@ffi_enums)
     end
 
+    # @param symbol
+    # @return [FFI::Enum]
+    # Find an enum by a symbol it contains.
     def enum_value(symbol)
       @ffi_enums.__map_symbol(symbol)
     end
 
+    # @param [DataConverter, Type, Struct, Symbol] t type to find
+    # @return [Type]
+    # Find a type definition.
     def find_type(t)
       if t.kind_of?(Type)
         t
-      
+
       elsif defined?(@ffi_typedefs) && @ffi_typedefs.has_key?(t)
         @ffi_typedefs[t]
 
@@ -283,7 +476,7 @@ module FFI
       elsif t.is_a?(DataConverter)
         # Add a typedef so next time the converter is used, it hits the cache
         typedef Type::Mapped.new(t), t
-      
+
       end || FFI.find_type(t)
     end
   end