From: Eric Wong Date: 2018-09-12T21:07:05+00:00 Subject: [ruby-core:88963] Re: [Ruby trunk Feature#15074] Create 'official' C API documentation on ruby-doc.org 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: