Feedback on documentation
Created originally on Bitbucket by nlgranger
Hi, Thank you very much for this library. I'd like to give some feedback from my first experience with this library.
- The Overview seems to oppose a "main mode" to API and ABI modes, my understanding is that "main mode" is just a minimal example of API out-of-line mode to showcase the library and should be presented as such, then the API/ABI stuff
- API/ABI and in-line/out-of-line are orthogonal notions, right? Then it might be better to introduce them separately.
- 'Out-of-line' does not have an intuitive signification to me, I suggest precompiled. In-line might be renamed dynamic which makes sense with the use of dlopen.
- Mayby emphasize the distinction between the input of
FFI.cdef
and actual C headers. The way I see it,FFI.cdef
takes a pseudo C code which specifies which elements of a C library must be bound into the python module. It is different from the actual C headers, which btw are also needed when usingFFI.set_source
. - The term Embedding seems a bit vague to me, I suggest splitting the Overview page in two with something like "calling c stuff from python" and "calling python stuff from C"
- The ellipsis "..." needs a documentation of its own. In particular, it's not obvious that you can't use it in ABI mode.
- The reference is incomplete,
FFI.cdef
,FFI.set_source
andFFI.compile
are missing.
I am by no means an expert, so I don't expect all of the above to be relevant and please don't take this as criticism, it's merely a feedback. I suppose I can help or make more detailed propositions for this issue, but I will need supervision and guidelines.