* ext/.document (fiddle): Remove duplicate entry

* ext/fiddle:  Complete documentation of Fiddle.  Patch by Vincent
  Batts.  [#5192]


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@32981 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

3 files changed, 39 insertions, 0 deletions

diff --git a/ext/fiddle/lib/fiddle.rb b/ext/fiddle/lib/fiddle.rb
index 8b8c069b03..7d55a1f7ad 100644
--- a/ext/fiddle/lib/fiddle.rb
+++ b/ext/fiddle/lib/fiddle.rb
@@ -4,22 +4,29 @@ require 'fiddle/closure'
 require 'dl' unless Object.const_defined?(:DL)
 
 module Fiddle
+
+  # A reference to DL::CPtr
   Pointer = DL::CPtr
 
   if WINDOWS
+    # Returns the last win32 +Error+ of the current executing +Thread+ or nil
+    # if none
     def self.win32_last_error
       Thread.current[:__FIDDLE_WIN32_LAST_ERROR__]
     end
 
+    # Sets the last win32 +Error+ of the current executing +Thread+ to +error+
     def self.win32_last_error= error
       Thread.current[:__FIDDLE_WIN32_LAST_ERROR__] = error
     end
   end
 
+  # Returns the last +Error+ of the current executing +Thread+ or nil if none
   def self.last_error
     Thread.current[:__FIDDLE_LAST_ERROR__]
   end
 
+  # Sets the last +Error+ of the current executing +Thread+ to +error+
   def self.last_error= error
     Thread.current[:__DL2_LAST_ERROR__] = error
     Thread.current[:__FIDDLE_LAST_ERROR__] = error
diff --git a/ext/fiddle/lib/fiddle/closure.rb b/ext/fiddle/lib/fiddle/closure.rb
index dc2b7a65be..beb90ecbe5 100644
--- a/ext/fiddle/lib/fiddle/closure.rb
+++ b/ext/fiddle/lib/fiddle/closure.rb
@@ -1,14 +1,45 @@
 module Fiddle
   class Closure
+
+    # the C type of the return of the FFI closure
     attr_reader :ctype
+
+    # arguments of the FFI closure
     attr_reader :args
 
+    # Extends Fiddle::Closure to allow for building the closure in a block
     class BlockCaller < Fiddle::Closure
+
+      # == Description
+      #
+      # Construct a new BlockCaller object.
+      #
+      # * +ctype+ is the C type to be returned
+      # * +args+ are passed the callback
+      # * +abi+ is the abi of the closure
+      #
+      # If there is an error in preparing the +ffi_cif+ or +ffi_prep_closure+,
+      # then a RuntimeError will be raised.
+      #
+      # == Example
+      #
+      #   include Fiddle
+      #
+      #   cb = Closure::BlockCaller.new(TYPE_INT, [TYPE_INT]) do |one|
+      #     one
+      #   end
+      #
+      #   func = Function.new(cb, [TYPE_INT], TYPE_INT)
+      #
       def initialize ctype, args, abi = Fiddle::Function::DEFAULT, &block
         super(ctype, args, abi)
         @block = block
       end
 
+      # Calls the constructed BlockCaller, with +args+
+      #
+      # For an example see Fiddle::Closure::BlockCaller.new
+      #
       def call *args
         @block.call(*args)
       end
diff --git a/ext/fiddle/lib/fiddle/function.rb b/ext/fiddle/lib/fiddle/function.rb
index 7b9e735874..1657682498 100644
--- a/ext/fiddle/lib/fiddle/function.rb
+++ b/ext/fiddle/lib/fiddle/function.rb
@@ -1,5 +1,6 @@
 module Fiddle
   class Function
+    # The ABI of the Function.
     attr_reader :abi
   end
 end