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>