Add documentation for ArrayType, Buffer, DynamicLibrary, Function, Enum, Enums

and ConstGenerator.

3 files changed, 116 insertions, 17 deletions

diff --git a/lib/ffi/enum.rb b/lib/ffi/enum.rb
index 7df769d..a68f16b 100644
--- a/lib/ffi/enum.rb
+++ b/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
diff --git a/lib/ffi/pointer.rb b/lib/ffi/pointer.rb
index 16d2ecc..46fc384 100644
--- a/lib/ffi/pointer.rb
+++ b/lib/ffi/pointer.rb
@@ -21,6 +21,8 @@
 require 'ffi/platform'
 module FFI
   class Pointer
+    
+    # Pointer size
     SIZE = Platform::ADDRESS_SIZE / 8
 
     # Return the size of a pointer on the current platform, in bytes
diff --git a/lib/ffi/tools/const_generator.rb b/lib/ffi/tools/const_generator.rb
index 7267891..2a5436b 100644
--- a/lib/ffi/tools/const_generator.rb
+++ b/lib/ffi/tools/const_generator.rb
@@ -3,23 +3,38 @@ require 'open3'
 
 module FFI
 
-  ##
   # ConstGenerator turns C constants into ruby values.
-
+  #
+  # @example a simple example for stdio
+  #  cg = FFI::ConstGenerator.new('stdio') do |gen|
+  #    gen.const(:SEEK_SET)
+  #    gen.const('SEEK_CUR')
+  #    gen.const('seek_end')   # this constant does not exist
+  #  end            # #calculate called automatically at the end of the block
+  #
+  #  cg['SEEK_SET'] # => 0
+  #  cg['SEEK_CUR'] # => 1
+  #  cg['seek_end'] # => nil
+  #  cg.to_ruby     # => "SEEK_SET = 0\nSEEK_CUR = 1\n# seek_end not available"
   class ConstGenerator
     @options = {}
     attr_reader :constants
 
-    ##
     # Creates a new constant generator that uses +prefix+ as a name, and an
     # options hash.
     #
-    # The only option is :required, which if set to true raises an error if a
+    # The only option is +:required+, which if set to +true+ raises an error if a
     # constant you have requested was not found.
-    #
-    # When passed a block, #calculate is automatically called at the end of
-    # the block, otherwise you must call it yourself.
-
+    # 
+    # @param [#to_s] prefix
+    # @param [Hash] options
+    # @return 
+    # @option options [Boolean] :required
+    # @overload initialize(prefix, options)
+    # @overload initialize(prefix, options) { |gen| ... }
+    #  @yieldparam [ConstGenerator] gen new generator is passed to the block
+    #  When passed a block, {#calculate} is automatically called at the end of
+    #  the block, otherwise you must call it yourself.
     def initialize(prefix = nil, options = {})
       @includes = []
       @constants = {}
@@ -33,23 +48,40 @@ module FFI
         calculate self.class.options.merge(options)
       end
     end
+    # Set class options
+    # These options are merged with {#initialize} options when it is called with a block.
+    # @param [Hash] options
+    # @return [Hash] class options
     def self.options=(options)
       @options = options
     end
+    # Get class options.
+    # @return [Hash] class options
     def self.options
       @options
     end
+    # @param [String] name
+    # @return constant value
+    # Access a constant by name.
     def [](name)
       @constants[name].value
     end
 
-    ##
-    # Request the value for C constant +name+.  +format+ is a printf format
-    # string to print the value out, and +cast+ is a C cast for the value.
-    # +ruby_name+ allows you to give the constant an alternate ruby name for
-    # #to_ruby.  +converter+ or +converter_proc+ allow you to convert the
-    # value from a string to the appropriate type for #to_ruby.
-
+    # Request the value for C constant +name+.
+    #
+    # @param [#to_s] name C constant name
+    # @param [String] format a printf format string to print the value out
+    # @param [String] cast a C cast for the value
+    # @param ruby_name alternate ruby name for {#to_ruby}
+    #
+    # @overload const(name, format=nil, cast='', ruby_name=nil, converter=nil)
+    #  +converter+ is a Method or a Proc.
+    #  @param [#call] converter convert the value from a string to the appropriate
+    #   type for {#to_ruby}.
+    # @overload const(name, format=nil, cast='', ruby_name=nil) { |value| ... }
+    #  Use a converter block. This block convert the value from a string to the 
+    #  appropriate type for {#to_ruby}.
+    #  @yieldparam value constant value
     def const(name, format = nil, cast = '', ruby_name = nil, converter = nil,
               &converter_proc)
       format ||= '%d'
@@ -66,6 +98,11 @@ module FFI
       return const
     end
 
+    # Calculate constants values.
+    # @param [Hash] options
+    # @option options [String] :cppflags flags for C compiler
+    # @return [nil]
+    # @raise if a constant is missing and +:required+ was set to +true+ (see {#initialize})
     def calculate(options = {})
       binary = File.join Dir.tmpdir, "rb_const_gen_bin_#{Process.pid}"
 
@@ -115,6 +152,9 @@ module FFI
       end
     end
 
+    # Dump constants to +io+.
+    # @param [#puts] io
+    # @return [nil]
     def dump_constants(io)
       @constants.each do |name, constant|
         name = [@prefix, name].join '.' if @prefix
@@ -122,10 +162,9 @@ module FFI
       end
     end
 
-    ##
     # Outputs values for discovered constants.  If the constant's value was
     # not discovered it is not omitted.
-
+    # @return [String]
     def to_ruby
       @constants.sort_by { |name,| name }.map do |name, constant|
         if constant.value.nil? then
@@ -136,17 +175,27 @@ module FFI
       end.join "\n"
     end
 
+    # Add a C include file to calculate constants from.
+    # @param [String] i include file
+    # @return [Array<String>] array of include files (stdio.h is omitted)
     def include(i)
       @includes << i
     end
 
   end
 
+  # This class hold constants for {ConstGenerator}
   class ConstGenerator::Constant
 
     attr_reader :name, :format, :cast
     attr_accessor :value
 
+    # @param [#to_s] name
+    # @param [String] format a printf format string to print the value out
+    # @param [String] cast a C cast for the value
+    # @param ruby_name alternate ruby name for {#to_ruby}
+    # @param [#call] converter convert the value from a string to the appropriate
+    #  type for {#to_ruby}.
     def initialize(name, format, cast, ruby_name = nil, converter=nil)
       @name = name
       @format = format
@@ -156,6 +205,8 @@ module FFI
       @value = nil
     end
 
+    # Return constant value (converted if a +converter+ was defined).
+    # @return constant value.
     def converted_value
       if @converter
         @converter.call(@value)
@@ -164,10 +215,14 @@ module FFI
       end
     end
 
+    # get constant ruby name
+    # @return [String]
     def ruby_name
       @ruby_name || @name
     end
 
+    # Get an evaluable string from constant.
+    # @return [String]
     def to_ruby
       "#{ruby_name} = #{converted_value}"
     end