Hi Colin!
Not sure how to answer the branch question, but I definitely found there is already much more documentation on FFI than I had realized. In fact going through this I would say that all the documentation would do better to be reorganized and I'll open up a separate issue for that.
Speaking to the existing FFI documentation, there are now 4 hits if you search FFI in ReadTheDocs. Here are my initial thoughts on how they might be reorganized, what do you think? First, I'd say all the FFI information now should be collected into one place, under Language Reference.
ASIDE: I think it would be awesome to have a tutorial "How to wrap" guiding us through how to make wrappers for one or more of the many important C libraries. That would also provide a recipe to jump start the Idris library wrapping industry as has been so useful making Haskell a practical programming language.
Specifics on the current FFI documentation:
1. Docs » Language Reference » New Foreign Function Interface
-- should be the main topic header for FFI
-- the word "New" should be dropped, there's no old one
2. Docs » Language Reference » Miscellaneous / C Heap
-- awesome stuff, but should be merged into Reference.FFI where at the very least the context is clear, otherwise we should describe the general importance of memory management primitives (and perhaps "idrisize" that with uniqueness types or some cool memory abstraction).
3. Docs » Language Reference » Miscellaneous / Type Providers
-- This seems to be the only source for the material it contains, for instance Include and Linker Directives, so although it's written in tutorial style I think it belongs in reference! Also, the material here is "reference" not "tutorial" in nature, because it isn't telling how some exemplary thing was accomplished, it's documenting the full range of things that are possible.
5. (not sure)
libs/contrib/CFFI/Memory.idr
-- I'm not sure i understand this completely, but there seems to be some material here (malloc / calloc) that doesn't appear in the documentation.
6. Edwin's earlier post on this thread.
-- The compile-idris paper section 4 describes general FFI (not only to C) and provides / proposes some additional abstractions by which FFI might be made to look and behave more succinctly in Idris.
-- to some extent the chapter is suggestive of what might be done rather than how Idris actually works today, so is a development or even a small research project
-- I don't understand things well enough to do much more than summarize. If we have nothing better we could just do that for now, perhaps add a final section called "FFI to Languages besides C, with some suggested abstractions".
-- we could certainly add a reference to the paper, after a short summary, which might be fine for release 1.0.
Allan