[ruby/fiddle] Update documentation

(https://github.com/ruby/fiddle/pull/119)

The documentation for `Fiddle.dlwrap` and `Fiddle.dlunwrap` were not
very accurate and pretty confusing. This commit updates the
documentation so it's easier to understand what the methods do.

1 files changed, 19 insertions, 14 deletions

diff --git a/ext/fiddle/fiddle.c b/ext/fiddle/fiddle.c
index c06cd5634a..aee3a4b42b 100644
--- a/ext/fiddle/fiddle.c
+++ b/ext/fiddle/fiddle.c
@@ -58,18 +58,16 @@ rb_fiddle_free(VALUE self, VALUE addr)
 /*
  * call-seq: Fiddle.dlunwrap(addr)
  *
- * Returns the hexadecimal representation of a memory pointer address +addr+
+ * Returns the Ruby object stored at the memory address +addr+
  *
  * Example:
  *
- *   lib = Fiddle.dlopen('/lib64/libc-2.15.so')
- *   => #<Fiddle::Handle:0x00000001342460>
- *
- *   lib['strcpy'].to_s(16)
- *   => "7f59de6dd240"
- *
- *   Fiddle.dlunwrap(Fiddle.dlwrap(lib['strcpy'].to_s(16)))
- *   => "7f59de6dd240"
+ *    >> x = Object.new
+ *    => #<Object:0x0000000107c7d870>
+ *    >> Fiddle.dlwrap(x)
+ *    => 4425504880
+ *    >> Fiddle.dlunwrap(_)
+ *    => #<Object:0x0000000107c7d870>
  */
 VALUE
 rb_fiddle_ptr2value(VALUE self, VALUE addr)
@@ -80,15 +78,22 @@ rb_fiddle_ptr2value(VALUE self, VALUE addr)
 /*
  * call-seq: Fiddle.dlwrap(val)
  *
- * Returns a memory pointer of a function's hexadecimal address location +val+
+ * Returns the memory address of the Ruby object stored at +val+
  *
  * Example:
  *
- *   lib = Fiddle.dlopen('/lib64/libc-2.15.so')
- *   => #<Fiddle::Handle:0x00000001342460>
+ *    >> x = Object.new
+ *    => #<Object:0x0000000107c7d870>
+ *    >> Fiddle.dlwrap(x)
+ *    => 4425504880
+ *
+ * In the case +val+ is not a heap allocated object, this method will return
+ * the tagged pointer value.
+ *
+ * Example:
  *
- *   Fiddle.dlwrap(lib['strcpy'].to_s(16))
- *   => 25522520
+ *    >> Fiddle.dlwrap(123)
+ *    => 247
  */
 static VALUE
 rb_fiddle_value2ptr(VALUE self, VALUE val)