ffi · Sep 20, 2011 · Sep 18, 2011
diff --git a/ext/ffi_c/AbstractMemory.c b/ext/ffi_c/AbstractMemory.c
@@ -458,12 +458,12 @@ memory_get_bytes(VALUE self, VALUE offset, VALUE length)
 
 /*
  * call-seq: memory.put_bytes(offset, str, index=0, length=nil)
- * Return string contained in memory.
+ * Put a string in memory.
  * @param [Numeric] offset point in buffer to start from
  * @param [String] str string to put to memory
  * @param [Numeric] index
  * @param [Numeric] length string's length in bytes. If nil, a (memory size - offset) length string is returned).
- * @return [String]
+ * @return [self]
  * @raise {IndexError} if +length+ is too great
  * @raise {NullPointerError} if memory not initialized
  * @raise {RangeError} if +index+ is negative, or if index+length is greater than size of string
@@ -521,7 +521,7 @@ memory_read_bytes(VALUE self, VALUE length)
  * @param [String] str string to put to memory
  * @param [Numeric] index
  * @param [Numeric] length string's length in bytes. If nil, a (memory size - offset) length string is returned).
- * @return [String]
+ * @return [self]
  * equivalent to :
  *  memory.put_bytes(0, str, index, length)
  */
@@ -681,7 +681,9 @@ rbffi_AbstractMemory_Init(VALUE moduleFFI)
      */
     VALUE classMemory = rb_define_class_under(moduleFFI, "AbstractMemory", rb_cObject);
     rbffi_AbstractMemoryClass = classMemory;
-    /* Document-variable: FFI::AbstractMemory */
+    /* 
+     * Document-variable: FFI::AbstractMemory 
+     */
     rb_global_variable(&rbffi_AbstractMemoryClass);
     rb_define_alloc_func(classMemory, memory_allocate);
 

diff --git a/ext/ffi_c/MappedType.c b/ext/ffi_c/MappedType.c
@@ -50,6 +50,12 @@ mapped_allocate(VALUE klass)
     return obj;
 }
 
+/*
+ * call-seq: initialize(converter)
+ * @param [#native_type, #to_native, #from_native] converter +converter+ must respond to
+ *  all these methods
+ * @return [self]
+ */
 static VALUE
 mapped_initialize(VALUE self, VALUE rbConverter)
 {
@@ -88,6 +94,11 @@ mapped_mark(MappedType* m)
     rb_gc_mark(m->rbConverter);
 }
 
+/*
+ * call-seq: mapped_type.native_type
+ * @return [Type]
+ * Get native type of mapped type.
+ */
 static VALUE
 mapped_native_type(VALUE self)
 {
@@ -97,6 +108,10 @@ mapped_native_type(VALUE self)
     return m->rbType;
 }
 
+/*
+ * call-seq: mapped_type.to_native(*args)
+ * @param args depends on {FFI::DataConverter} used to initialize +self+
+ */
 static VALUE
 mapped_to_native(int argc, VALUE* argv, VALUE self)
 {
@@ -107,6 +122,10 @@ mapped_to_native(int argc, VALUE* argv, VALUE self)
     return rb_funcall2(m->rbConverter, id_to_native, argc, argv);
 }
 
+/*
+ * call-seq: mapped_type.from_native(*args)
+ * @param args depends on {FFI::DataConverter} used to initialize +self+
+ */
 static VALUE
 mapped_from_native(int argc, VALUE* argv, VALUE self)
 {
@@ -121,6 +140,9 @@ void
 rbffi_MappedType_Init(VALUE moduleFFI)
 {
 
+    /* 
+     * Document-class: FFI::Type::Mapped
+     */
     rbffi_MappedTypeClass = rb_define_class_under(rbffi_TypeClass, "Mapped", rbffi_TypeClass);
 
     rb_global_variable(&rbffi_MappedTypeClass);

diff --git a/ext/ffi_c/Pointer.c b/ext/ffi_c/Pointer.c
@@ -68,6 +68,13 @@ ptr_allocate(VALUE klass)
     return obj;
 }
 
+/*
+ * call-seq: initialize(type, address)
+ * @param [Type] type type for pointer
+ * @param [Integer, Pointer] address base address for pointer, or another pointer
+ * @return [self]
+ * Create a new pointer from a {Type} and a base adresse or another {Pointer}.
+ */
 static VALUE
 ptr_initialize(int argc, VALUE* argv, VALUE self)
 {
@@ -117,6 +124,16 @@ ptr_initialize(int argc, VALUE* argv, VALUE self)
     return self;
 }
 
+/*
+ * call-seq: ptr.initialize_copy(other)
+ * @param [Pointer] other source for cloning or dupping
+ * @return [self]
+ * @raise {RuntimeError} if +other+ is an unbounded memory area, or is unreable/unwritable
+ * @raise {NoMemError} if failed to allocate memory for new object
+ * DO NOT CALL THIS METHOD.
+ *
+ * This method is internally used by #dup and #clone. Memory contents is copied from +other+.
+ */
 static VALUE
 ptr_initialize_copy(VALUE self, VALUE other)
 {
@@ -179,6 +196,13 @@ slice(VALUE self, long offset, long size)
     return retval;
 }
 
+/* 
+ * Document-method: +
+ * call-seq: ptr + offset
+ * @param [Numeric] offset
+ * @return [Pointer]
+ * Return a new {Pointer} from an existing pointer and an +offset+.
+ */
 static VALUE
 ptr_plus(VALUE self, VALUE offset)
 {
@@ -190,12 +214,25 @@ ptr_plus(VALUE self, VALUE offset)
     return slice(self, off, ptr->size == LONG_MAX ? LONG_MAX : ptr->size - off);
 }
 
+/*
+ * call-seq: ptr.slice(offset, length)
+ * @param [Numeric] offset
+ * @param [Numeric] length
+ * @return [Pointer]
+ * Return a new {Pointer} from an existing one. This pointer points on same contents 
+ * from +offset+ for a length +length+.
+ */
 static VALUE
 ptr_slice(VALUE self, VALUE rbOffset, VALUE rbLength)
 {
     return slice(self, NUM2LONG(rbOffset), NUM2LONG(rbLength));
 }
 
+/*
+ * call-seq: ptr.inspect
+ * @return [String]
+ * Inspect pointer object.
+ */
 static VALUE
 ptr_inspect(VALUE self)
 {
@@ -214,6 +251,12 @@ ptr_inspect(VALUE self)
     return rb_str_new2(buf);
 }
 
+/*
+ * Document-method: null?
+ * call-seq: ptr.null?
+ * @return [Boolean]
+ * Return +true+ if +self+ is a {NULL} pointer.
+ */
 static VALUE
 ptr_null_p(VALUE self)
 {
@@ -224,6 +267,12 @@ ptr_null_p(VALUE self)
     return ptr->memory.address == NULL ? Qtrue : Qfalse;
 }
 
+/*
+ * Document-method: ==
+ * call-seq: ptr == other
+ * @param [Pointer] other
+ * Check equality between +self+ and +other+. Equality is tested on {#address}.
+ */
 static VALUE
 ptr_equals(VALUE self, VALUE other)
 {
@@ -234,6 +283,11 @@ ptr_equals(VALUE self, VALUE other)
     return ptr->memory.address == POINTER(other)->address ? Qtrue : Qfalse;
 }
 
+/*
+ * call-seq: ptr.address
+ * @return [Numeric] pointer's base address
+ * Return +self+'s base address (alias: #to_i).
+ */
 static VALUE
 ptr_address(VALUE self)
 {
@@ -250,6 +304,15 @@ ptr_address(VALUE self)
 # define SWAPPED_ORDER LITTLE_ENDIAN
 #endif
 
+/*
+ * Get or set +self+'s endianness
+ * @overload ptr.order
+ *  @return [:big, :little] endianness of +self+
+ * @overload ptr.order(order)
+ *  @param  [Symbol] order endianness to set (+:little+, +:big+ or +:network+). +:big+ and +:network+ 
+ *   are synonymous.
+ *  @return [self]
+ */
 static VALUE
 ptr_order(int argc, VALUE* argv, VALUE self)
 {
@@ -289,6 +352,11 @@ ptr_order(int argc, VALUE* argv, VALUE self)
 }
 
 
+/*
+ * call-seq: ptr.free
+ * @return [self]
+ * Free memory pointed by +self+.
+ */
 static VALUE
 ptr_free(VALUE self)
 {
@@ -307,6 +375,12 @@ ptr_free(VALUE self)
     return self;
 }
 
+/*
+ * call-seq: ptr.autorelease = autorelease
+ * @param [Boolean] autorelease
+ * @return [Boolean] +autorelease+
+ * Set +autorelease+ attribute. See also Autorelease section.
+ */
 static VALUE
 ptr_autorelease(VALUE self, VALUE autorelease)
 {
@@ -318,6 +392,11 @@ ptr_autorelease(VALUE self, VALUE autorelease)
     return autorelease;
 }
 
+/*
+ * call-seq: ptr.autorelease?
+ * @return [Boolean]
+ * Get +autorelease+ attribute. See also Autorelease section.
+ */
 static VALUE
 ptr_autorelease_p(VALUE self)
 {
@@ -350,7 +429,19 @@ rbffi_Pointer_Init(VALUE moduleFFI)
 {
     VALUE rbNullAddress = ULL2NUM(0);
 
+    /* 
+     * Document-class: FFI::Pointer
+     * Pointer class is used to manage C pointers with ease. A {Pointer} object is defined by his
+     * {#address} (as a C pointer). It permits additions with an integer for pointer arithmetic.
+     *
+     * ==Autorelease
+     * A pointer object may autorelease his contents when freed (by default). This behaviour may be
+     * changed with {#autorelease=} method.
+     */
     rbffi_PointerClass = rb_define_class_under(moduleFFI, "Pointer", rbffi_AbstractMemoryClass);
+    /*
+     * Document-variable: Pointer
+     */
     rb_global_variable(&rbffi_PointerClass);
 
     rb_define_alloc_func(rbffi_PointerClass, ptr_allocate);