Merge pull request #468 from paddor/master

minor documentation and code style improvements

5 files changed, 52 insertions, 42 deletions

diff --git a/lib/ffi/autopointer.rb b/lib/ffi/autopointer.rb
index e6946d8..889a3e3 100644
--- a/lib/ffi/autopointer.rb
+++ b/lib/ffi/autopointer.rb
@@ -34,27 +34,29 @@ module FFI
     extend DataConverter
 
     # @overload initialize(pointer, method)
-    #  @param [Pointer] pointer
-    #  @param [Method] method
-    #  @return [self]
-    #  The passed Method will be invoked at GC time.
+    #   @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.
+    #   @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.
+    #   @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.
+    #   @param pointer [Pointer]
+    #   @return [self]
+    #   The pointer's release() class method will be invoked at GC time.
     #
     # @note The safest, and therefore preferred, calling
     #  idiom is to pass a Method as the second parameter. Example usage:
@@ -79,11 +81,15 @@ module FFI
         || ptr.kind_of?(MemoryPointer) || ptr.kind_of?(AutoPointer)
 
       @releaser = if proc
-                    raise RuntimeError.new("proc must be callable") unless proc.respond_to?(:call)
+                    if not proc.respond_to?(:call)
+                      raise RuntimeError.new("proc must be callable")
+                    end
                     CallableReleaser.new(ptr, proc)
 
                   else
-                    raise RuntimeError.new("no release method defined") unless self.class.respond_to?(:release)
+                    if not self.class.respond_to?(:release)
+                      raise RuntimeError.new("no release method defined")
+                    end
                     DefaultReleaser.new(ptr, self.class)
                   end
 
@@ -143,16 +149,15 @@ module FFI
       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.
+    # 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
       # @param [Pointer] ptr
       # @return [nil]
-      # Release +ptr+ by using his #release class method.
+      # Release +ptr+ using the {release} class method of its class.
       def release(ptr)
         @proc.release(ptr)
       end
@@ -161,7 +166,9 @@ module FFI
     # CallableReleaser is a {Releaser} used when an {AutoPointer} is defined with a
     # Proc or a Method.
     class CallableReleaser < Releaser
-      # Release +ptr+ by using Proc or Method defined at +ptr+ {AutoPointer#initialize initialization}.
+      # Release +ptr+ by using Proc or Method defined at +ptr+
+      # {AutoPointer#initialize initialization}.
+      #
       # @param [Pointer] ptr
       # @return [nil]
       def release(ptr)
@@ -175,7 +182,9 @@ module FFI
     # @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)
+      if not self.respond_to?(:release)
+        raise RuntimeError.new("no release method defined for #{self.inspect}")
+      end
       Type::POINTER
     end
 
diff --git a/lib/ffi/enum.rb b/lib/ffi/enum.rb
index 0e84ba7..846b836 100644
--- a/lib/ffi/enum.rb
+++ b/lib/ffi/enum.rb
@@ -146,7 +146,7 @@ module FFI
     def symbol_map
       @kv_map
     end
-    
+
     alias to_h symbol_map
     alias to_hash symbol_map
 
@@ -168,7 +168,5 @@ module FFI
     def from_native(val, ctx)
       @vk_map[val] || val
     end
-
   end
-
 end
diff --git a/lib/ffi/pointer.rb b/lib/ffi/pointer.rb
index fec7671..bfd9406 100644
--- a/lib/ffi/pointer.rb
+++ b/lib/ffi/pointer.rb
@@ -33,7 +33,7 @@
 require 'ffi/platform'
 module FFI
   class Pointer
-    
+
     # Pointer size
     SIZE = Platform::ADDRESS_SIZE / 8
 
diff --git a/lib/ffi/tools/types_generator.rb b/lib/ffi/tools/types_generator.rb
index 125a1a0..ff24ec5 100644
--- a/lib/ffi/tools/types_generator.rb
+++ b/lib/ffi/tools/types_generator.rb
@@ -1,7 +1,7 @@
 require 'tempfile'
 
 module FFI
-  
+
   # @private
   class TypesGenerator
 
@@ -65,7 +65,7 @@ module FFI
           typedefs = `#{cmd} #{io.path}`
         end
       end
-      
+
       code = ""
 
       typedefs.each_line do |type|
@@ -73,11 +73,11 @@ module FFI
         next unless type =~ /typedef/
         # Ignore unions or structs
         next if type =~ /union|struct/
-        
+
         # strip off the starting typedef and ending ;
         type.gsub!(/^(.*typedef\s*)/, "")
         type.gsub!(/\s*;\s*$/, "")
-    
+
         parts = type.split(/\s+/)
         def_type   = parts.join(" ")
 
@@ -99,7 +99,7 @@ module FFI
           else
             final_type = parts.pop
           end
-          
+
           def_type = case type
                      when /__QI__/   then "char"
                      when /__HI__/   then "short"
@@ -114,7 +114,7 @@ module FFI
           final_type = parts.pop
           def_type   = parts.join(" ")
         end
-        
+
         if type = TYPE_MAP[def_type]
           code << "rbx.platform.typedef.#{final_type} = #{type}\n"
           TYPE_MAP[final_type] = TYPE_MAP[def_type]
@@ -129,7 +129,6 @@ module FFI
 
       code
     end
-
   end
 end
 
diff --git a/lib/ffi/types.rb b/lib/ffi/types.rb
index 4e48a2c..ddad36e 100644
--- a/lib/ffi/types.rb
+++ b/lib/ffi/types.rb
@@ -65,7 +65,6 @@ module FFI
 
     elsif name.is_a?(DataConverter)
       (type_map || TypeDefs)[name] = Type::Mapped.new(name)
-    
     else
       raise TypeError, "unable to resolve type '#{name}'"
     end
@@ -149,19 +148,24 @@ module FFI
       :varargs => Type::VARARGS,
   })
 
-  
+  # This will convert a pointer to a Ruby string (just like `:string`), but
+  # also allow to work with the pointer itself. This is useful when you want
+  # a Ruby string already containing a copy of the data, but also the pointer
+  # to the data for you to do something with it, like freeing it, in case the
+  # library handed the memory to off to the caller (Ruby-FFI).
+  #
+  # It's {typedef}'d as +:strptr+.
   class StrPtrConverter
     extend DataConverter
     native_type Type::POINTER
 
     # @param [Pointer] val
-    # @param ctx
+    # @param ctx not used
     # @return [Array(String, Pointer)]
     # Returns a [ String, Pointer ] tuple so the C memory for the string can be freed
     def self.from_native(val, ctx)
       [ val.null? ? nil : val.get_string(0), val ]
     end
-
   end
 
   typedef(StrPtrConverter, :strptr)