ffi 1.2.1 → 1.3.0

data/lib/ffi/struct.rb

@@ -27,20 +27,32 @@ module FFI
 
   class StructLayout
 
+    # @return [Array<Array(Symbol, Numeric)>
+    # Get an array of tuples (field name, offset of the field).
     def offsets
       members.map { |m| [ m, self[m].offset ] }
     end
 
+    # @return [Numeric]
+    # Get the offset of a field.
     def offset_of(field_name)
       self[field_name].offset
     end
 
+    # An enum {Field} in a {StructLayout}.
     class Enum < Field
-      
+
+      # @param [AbstractMemory] ptr pointer on a {Struct}
+      # @return [Object]
+      # Get an object of type {#type} from memory pointed by +ptr+.
       def get(ptr)
         type.find(ptr.get_int(offset))
       end
 
+      # @param [AbstractMemory] ptr pointer on a {Struct}
+      # @param  value
+      # @return [nil]
+      # Set +value+ into memory pointed by +ptr+.
       def put(ptr, value)
         ptr.put_int(offset, type.find(value))
       end
@@ -77,61 +89,82 @@ module FFI
   
   class Struct
 
+    # Get struct size
+    # @return [Numeric]
     def size
       self.class.size
     end
 
+    # @return [Fixnum] Struct alignment
     def alignment
       self.class.alignment
     end
     alias_method :align, :alignment
 
+    # (see FFI::StructLayout#offset_of)
     def offset_of(name)
       self.class.offset_of(name)
     end
 
+    # (see FFI::StructLayout#members)
     def members
       self.class.members
     end
 
+    # @return [Array]
+    # Get array of values from Struct fields.
     def values
       members.map { |m| self[m] }
     end
 
+    # (see FFI::StructLayout#offsets)
     def offsets
       self.class.offsets
     end
 
+    # Clear the struct content.
+    # @return [self]
     def clear
       pointer.clear
       self
     end
 
+    # Get {Pointer} to struct content.
+    # @return [AbstractMemory]
     def to_ptr
       pointer
     end
 
+    # Get struct size
+    # @return [Numeric]
     def self.size
       defined?(@layout) ? @layout.size : defined?(@size) ? @size : 0
     end
 
+    # set struct size
+    # @param [Numeric] size
+    # @return [size]
     def self.size=(size)
       raise ArgumentError, "Size already set" if defined?(@size) || defined?(@layout)
       @size = size
     end
 
+    # @return (see Struct#alignment)
     def self.alignment
       @layout.alignment
     end
 
+    # (see FFI::Type#members)
     def self.members
       @layout.members
     end
 
+    # (see FFI::StructLayout#offsets)
     def self.offsets
       @layout.offsets
     end
 
+    # (see FFI::StructLayout#offset_of)
     def self.offset_of(name)
       @layout.offset_of(name)
     end
@@ -162,6 +195,7 @@ module FFI
 
     class ManagedStructConverter < StructByReference
 
+      # @param [Struct] struct_class
       def initialize(struct_class)
         super(struct_class)
 
@@ -169,6 +203,9 @@ module FFI
         @method = struct_class.method(:release)
       end
 
+      # @param [Pointer] ptr
+      # @param [nil] ctx
+      # @return [Struct]
       def from_native(ptr, ctx)
         struct_class.new(AutoPointer.new(ptr, @method))
       end
@@ -182,6 +219,33 @@ module FFI
     class << self
       public
 
+      # @return [StructLayout]
+      # @overload layout
+      #  @return [StructLayout]
+      #  Get struct layout.
+      # @overload layout(*spec)
+      #  @param [Array<Symbol, Integer>,Array(Hash)] spec
+      #  @return [StructLayout]
+      #  Create struct layout from +spec+.
+      #  @example Creating a layout from an array +spec+
+      #    class MyStruct < Struct
+      #      layout :field1, :int,
+      #             :field2, :pointer,
+      #             :field3, :string
+      #    end
+      #  @example Creating a layout from an array +spec+ with offset
+      #    class MyStructWithOffset < Struct
+      #      layout :field1, :int,
+      #             :field2, :pointer, 6,  # set offset to 6 for this field
+      #             :field3, :string
+      #    end
+      #  @example Creating a layout from a hash +spec+ (Ruby 1.9 only)
+      #    class MyStructFromHash < Struct
+      #      layout :field1 => :int,
+      #             :field2 => :pointer,
+      #             :field3 => :string
+      #    end
+      #  @note Creating a layout from a hash +spec+ is supported only for Ruby 1.9.
       def layout(*spec)
 #        raise RuntimeError, "struct layout already defined for #{self.inspect}" if defined?(@layout)
         return @layout if spec.size == 0
@@ -254,6 +318,11 @@ module FFI
 
       private
 
+      # @param [StructLayoutBuilder] builder
+      # @param [Hash] spec
+      # @return [builder]
+      # @raise if Ruby 1.8
+      # Add hash +spec+ to +builder+.
       def hash_layout(builder, spec)
         raise "Ruby version not supported" if RUBY_VERSION =~ /1.8.*/
         spec[0].each do |name, type|
@@ -261,6 +330,10 @@ module FFI
         end
       end
 
+      # @param [StructLayoutBuilder] builder
+      # @param [Array<Symbol, Integer>] spec
+      # @return [builder]
+      # Add array +spec+ to +builder+.
       def array_layout(builder, spec)
         i = 0
         while i < spec.size

data/lib/ffi/struct_layout_builder.rb

@@ -19,8 +19,11 @@
 #
 
 module FFI
+  
+  # Build a {StructLayout struct layout}.
   class StructLayoutBuilder
-    attr_reader :size, :alignment
+    attr_reader :size
+    attr_reader :alignment
     
     def initialize
       @size = 0
@@ -31,23 +34,42 @@ module FFI
       @fields = Array.new
     end
 
+    # @param [Numeric] size
+    # Set size attribute with +size+ only if +size+ is greater than attribute value.
     def size=(size)
       @size = size if size > @size
     end
 
+    # @param [Numeric] alignment
+    # Set alignment attribute with +alignment+ only if it is greater than attribute value.
     def alignment=(align)
       @alignment = align if align > @alignment
       @min_alignment = align
     end
 
+    # @param [Boolean] is_union
+    # @return [is_union]
+    # Set union attribute.
+    # Set to +true+ to build a {Union} instead of a {Struct}.
     def union=(is_union)
       @union = is_union
     end
 
+    # @return [Boolean]
+    # Building a {Union} or a {Struct} ?
     def union?
       @union
     end
 
+    # Set packed attribute
+    # @overload packed=(packed)
+    #  @param [Fixnum] packed
+    #  @return [packed]
+    #  Set alignment and packed attributes to +packed+.
+    # @overload packed=(packed)
+    #  @param packed
+    #  @return [0,1]
+    #  Set packed attribute.
     def packed=(packed)
       if packed.is_a?(Fixnum)
         @alignment = packed
@@ -58,6 +80,7 @@ module FFI
     end
 
 
+    # List of number types
     NUMBER_TYPES = [
       Type::INT8,
       Type::UINT8,
@@ -75,6 +98,12 @@ module FFI
       Type::BOOL,
     ]
 
+    # @param [String, Symbol] name name of the field
+    # @param [Array, DataConverter, Struct, StructLayout::Field, Symbol, Type] type type of the field
+    # @param [Numeric, nil] offset
+    # @return [self]
+    # Add a field to the builder.
+    # @note Setting +offset+ to +nil+ or +-1+ is equivalent to +0+.
     def add(name, type, offset = nil)
 
       if offset.nil? || offset == -1
@@ -92,18 +121,33 @@ module FFI
       return self
     end
 
+    # @param (see #add)
+    # @return (see #add)
+    # Same as {#add}.
+    # @see #add
     def add_field(name, type, offset = nil)
       add(name, type, offset)
     end
     
+    # @param (see #add)
+    # @return (see #add)
+    # Add a struct as a field to the builder.
     def add_struct(name, type, offset = nil)
       add(name, Type::Struct.new(type), offset)
     end
 
+    # @param name (see #add)
+    # @param type (see #add)
+    # @param [Numeric] count array length
+    # @param offset (see #add)
+    # @return (see #add)
+    # Add an array as a field to the builder.
     def add_array(name, type, count, offset = nil)
       add(name, Type::Array.new(type, count), offset)
     end
 
+    # @return [StructLayout]
+    # Build and return the struct layout.
     def build
       # Add tail padding if the struct is not packed
       size = @packed ? @size : align(@size, @alignment)
@@ -115,10 +159,15 @@ module FFI
 
     private
     
+    # @param [Numeric] offset
+    # @param [Numeric] align
+    # @return [Numeric]
     def align(offset, align)
       align + ((offset - 1) & ~(align - 1));
     end
 
+    # @param (see #add)
+    # @return [StructLayout::Field]
     def field_for_type(name, offset, type)
       field_class = case
       when type.is_a?(Type::Function)

data/lib/ffi/tools/generator.rb

@@ -1,4 +1,6 @@
 module FFI
+
+  # @private
   class Generator
 
     def initialize(ffi_name, rb_name, options = {})

data/lib/ffi/tools/generator_task.rb

@@ -16,6 +16,7 @@ require 'tempfile'
 ##
 # Rake task that calculates C structs for FFI::Struct.
 
+# @private
 class FFI::Generator::Task < Rake::TaskLib
 
   def initialize(rb_names)

data/lib/ffi/tools/types_generator.rb

@@ -1,6 +1,8 @@
 require 'tempfile'
 
 module FFI
+  
+  # @private
   class TypesGenerator
 
     ##

data/libtest/Benchmark.c

@@ -1,21 +1,7 @@
 /*
  * Copyright (c) 2007 Wayne Meissner. All rights reserved.
  *
- * All rights reserved.
- *
- * This file is part of ruby-ffi.
- *
- * This code is free software: you can redistribute it and/or modify it under
- * the terms of the GNU Lesser General Public License version 3 only, as
- * published by the Free Software Foundation.
- *
- * This code is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
- * version 3 for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * version 3 along with this work.  If not, see <http://www.gnu.org/licenses/>.
+ * For licensing, see LICENSE.SPECS
  */
 #include <sys/types.h>
 #include <stdint.h>

data/libtest/BoolTest.c

@@ -1,21 +1,7 @@
 /*
- * Copyright (c) 2009 Aman Gupta. All rights reserved.
- * 
- * All rights reserved.
+ * Copyright (c) 2007 Wayne Meissner. All rights reserved.
  *
- * This file is part of ruby-ffi.
- *
- * This code is free software: you can redistribute it and/or modify it under
- * the terms of the GNU Lesser General Public License version 3 only, as
- * published by the Free Software Foundation.
- *
- * This code is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
- * version 3 for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * version 3 along with this work.  If not, see <http://www.gnu.org/licenses/>.
+ * For licensing, see LICENSE.SPECS
  */
 
 #include <stdbool.h>

data/libtest/BufferTest.c

@@ -1,21 +1,7 @@
-/* 
- * Copyright (C) 2007 Wayne Meissner
- * 
- * All rights reserved.
+/*
+ * Copyright (c) 2007 Wayne Meissner. All rights reserved.
  *
- * This file is part of ruby-ffi.
- *
- * This code is free software: you can redistribute it and/or modify it under
- * the terms of the GNU Lesser General Public License version 3 only, as
- * published by the Free Software Foundation.
- *
- * This code is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
- * version 3 for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * version 3 along with this work.  If not, see <http://www.gnu.org/licenses/>.
+ * For licensing, see LICENSE.SPECS
  */
 
 

data/libtest/ClosureTest.c

@@ -1,21 +1,7 @@
 /*
  * Copyright (c) 2007 Wayne Meissner. All rights reserved.
- * 
- * All rights reserved.
  *
- * This file is part of ruby-ffi.
- *
- * This code is free software: you can redistribute it and/or modify it under
- * the terms of the GNU Lesser General Public License version 3 only, as
- * published by the Free Software Foundation.
- *
- * This code is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
- * version 3 for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * version 3 along with this work.  If not, see <http://www.gnu.org/licenses/>.
+ * For licensing, see LICENSE.SPECS
  */
 
 #include <stdlib.h>

data/libtest/EnumTest.c

@@ -1,21 +1,7 @@
 /*
  * Copyright (c) 2007 Wayne Meissner. All rights reserved.
  *
- * All rights reserved.
- *
- * This file is part of ruby-ffi.
- *
- * This code is free software: you can redistribute it and/or modify it under
- * the terms of the GNU Lesser General Public License version 3 only, as
- * published by the Free Software Foundation.
- *
- * This code is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
- * version 3 for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * version 3 along with this work.  If not, see <http://www.gnu.org/licenses/>.
+ * For licensing, see LICENSE.SPECS
  */
 
 int test_untagged_enum(int val) {