sameer.deshmukh93 / gmail.com wrote: > @hsbt what do you think about writing the docs within C API > files like `ruby.h`, `intern.h` and `extension.h` itself so > that ruby-doc.org can run doxygen on them to generate the > relevant documents? It will keep the documentation up-to-date > as well. (not hsbt, here) I think that's a better idea since files we import from ccan/* already do that. What's more important than API documentation (which is too narrow in scope IMHO) is: a) overall view of core internal data structures b) maintaining consistency in internal data structures Understanding APIs is much easier once data structures are understood and consistent. For example, I just committed my fix for [Bug #15050] in r64703, r64705 and r64706. The cause of the bug was having multiple sources of truth as to what constitutes a "root fiber". Multiple sources of truth is almost always a sign of bad data structure design as it is difficult-to-maintain for any application or database, leading to bugs. So the goal is to design and document data structures well, and use that as a foundation for good code. In my not so humble opinion, trying to understand with code/APIs before data structures is a total waste of time. Unsubscribe: <mailto:ruby-core-request / ruby-lang.org?subject=unsubscribe> <http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-core>