Subject: [ruby-ffi] Re: FFI core concepts wiki documentation |
From: Bryan Kearney |
Date: 11/10/09 9:37 AM |
To: ruby-ffi@googlegroups.com |
For me, it is about the examples. I would suggest adding some better doco around passing items by reference and arrays. I admit I am weak at C, so making the jump between a char*** and an array of strings was not intuitive. The JNA website [1] gives in doco examples to explain the harder concepts. I see some of this in [2] but it could be beefed up.
One of the areas in which the current wiki documentation could be improved is the Core Concepts category.
By this I mean, there's usually 3 - 5 key things about most things that you really need to have a good handle on in order to quickly become productive. Not that these cover every possible case, but they get you on the right path. FFI is likely similar.
I think it's important to keep things at a higher level but ensure the documentation is not so generic as to be useless. I also don't see value in re-documenting stuff like Pointers 101; there's plenty of other good sites within Google reach.
I plan on fleshing out http://wiki.github.com/ffi/ffi/core-concepts and would like to hear from those of you who have been working with FFI for awhile. The goal is to boil things down to the essence so that the page is as short and useful as it can be.
* What are the things you know now that you wish would have been in a Core Concepts page when you started?
* What were your top 3 "ah ha" discoveries you've made along the way?
* What other sites have provided good background info that have helped your FFI implementations?
* What are you top 3 gotchas/surprises when using FFI?
Jon