Following Max's advice I thought I just create issue for every open questions, so that is is easier to track things.

Bruno: I'm a fan of having literate code and using docco. I think it's a good practice to write the comments as docs when you're writing the code, and that way you don't have to figure out where the documentation is.
However, this isn't of course an alternative to a global API doc. As I mentioned, some projects do global APIs manually, like underscore, express, nodejs and socket.io. However, something automatic would be better. I'm currently exploring doxx as it seems to be able to generate a single doc for multiple modules. If doxx can solve most of the problem, we can then tweak it to generate an output with some of Biogems features.