Update documentation #119
Update documentation #119
Conversation
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.
| * >> x = Object.new | ||
| * => #<Object:0x0000000107c7d870> | ||
| * >> Fiddle.dlwrap(x) | ||
| * => 4425504880 | ||
| * >> Fiddle.dlunwrap(_) | ||
| * => #<Object:0x0000000107c7d870> |
There was a problem hiding this comment.
I believe we prefer examples syntax that is correct Ruby to be copy-pasted in some file and tried (also RDoc's syntax highlight wouldn't work otherwise, so I'd suggest...
| * >> x = Object.new | |
| * => #<Object:0x0000000107c7d870> | |
| * >> Fiddle.dlwrap(x) | |
| * => 4425504880 | |
| * >> Fiddle.dlunwrap(_) | |
| * => #<Object:0x0000000107c7d870> | |
| * x = Object.new | |
| * # => #<Object:0x0000000107c7d870> | |
| * addr = Fiddle.dlwrap(x) | |
| * # => 4425504880 | |
| * Fiddle.dlunwrap(addr) | |
| * # => #<Object:0x0000000107c7d870> |
| * >> x = Object.new | ||
| * => #<Object:0x0000000107c7d870> | ||
| * >> Fiddle.dlwrap(x) | ||
| * => 4425504880 | ||
| * >> Fiddle.dlunwrap(_) | ||
| * => #<Object:0x0000000107c7d870> |
There was a problem hiding this comment.
I believe we prefer examples syntax that is correct Ruby to be copy-pasted in some file and tried (also RDoc's syntax highlight wouldn't work otherwise), so I'd suggest...
| * >> x = Object.new | |
| * => #<Object:0x0000000107c7d870> | |
| * >> Fiddle.dlwrap(x) | |
| * => 4425504880 | |
| * >> Fiddle.dlunwrap(_) | |
| * => #<Object:0x0000000107c7d870> | |
| * x = Object.new | |
| * # => #<Object:0x0000000107c7d870> | |
| * addr = Fiddle.dlwrap(x) | |
| * # => 4425504880 | |
| * Fiddle.dlunwrap(addr) | |
| * # => #<Object:0x0000000107c7d870> |
| * >> x = Object.new | ||
| * => #<Object:0x0000000107c7d870> | ||
| * >> Fiddle.dlwrap(x) | ||
| * => 4425504880 |
There was a problem hiding this comment.
| * >> x = Object.new | |
| * => #<Object:0x0000000107c7d870> | |
| * >> Fiddle.dlwrap(x) | |
| * => 4425504880 | |
| * x = Object.new | |
| * # => #<Object:0x0000000107c7d870> | |
| * Fiddle.dlwrap(x) | |
| * # => 4425504880 |
| * >> Fiddle.dlwrap(123) | ||
| * => 247 |
There was a problem hiding this comment.
| * >> Fiddle.dlwrap(123) | |
| * => 247 | |
| * Fiddle.dlwrap(123) | |
| * # => 247 |
| * => 4425504880 | ||
| * | ||
| * In the case +val+ is not a heap allocated object, this method will return | ||
| * the tagged pointer value. |
There was a problem hiding this comment.
I can't say that "tagged pointer value" says anything to me in the context (and the example doesn't make it much clearer), but that's might be because of my ignorance :)
|
@zverok oops, thanks. I'll update the comments with your suggestions. I think explaining tagged pointers is probably outside the scope of Fiddle documentation. I expect developers that are messing around with pointers to Ruby objects need to know a bit about Ruby internals, but I wanted to at least call out that not all Ruby objects passed to |
(ruby/fiddle#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.
The documentation for
Fiddle.dlwrapandFiddle.dlunwrapwere not very accurate and pretty confusing. This commit updates the documentation so it's easier to understand what the methods do.