Issue #15074 has been updated by shevegen (Robert A. Heiler).


I think this would be nice to have. Matz often said that nobody minds if ruby
becomes faster :) - and I think nobody will mind if the documentation becomes
better (qualitatively; but also somewhat more documentation in general).

The link you gave is quite good (the one to github); it's not ideal, in my
opinion, when external documentation is better than the official one.

Perhaps part of the problem is that the changes to the documentation in 
regards to the official documentation come in small steps, such as improving
this or that example, adding this or that explanation. We need a little bit
of a comprehensive "global view" over the documentation. I understand that
you refer mostly to the C API level, but I think we can include this in 
general. Perhaps we could add some sort of wiki, so that contribution could
be made simpler, before these changes can be synced by a core committer
to svn/git. The reason I mention wiki is because it lowers the contribution
barrier; and it may be much easier for core committers to commit change 
when these are mentioned on the wiki. This could also help simplify 
external contributions, e. g. imagine if the author of the above link 
would add a disclaimer or otherwise approve that (some of) his changes
could be integrated into the official documentation, to help improve it.
Then we could integrate what is useful into the wiki, before it may
eventually be committed "into" ruby itself; a bit like with wikipedia,
and the wikipedia discussion-pages of main articles.

It may also be helpful to explore adding a fourth section here at the
bugtracker, solely for documentation-related issues (rather than bug,
feature or misc). But anyway, I do not want to digress too much from your
thread, so in general I agree to your statements in regards to improving
the C API documentation in the long run. 

----------------------------------------
Feature #15074: Create 'official' C API documentation on ruby-doc.org
https://bugs.ruby-lang.org/issues/15074#change-73896

* Author: v0dro (Sameer Deshmukh)
* Status: Open
* Priority: Normal
* Assignee: 
* Target version: 
----------------------------------------
Currently working with Ruby C API is basically reading a bunch of random
blogs and coming up with a solution based on inputs from various sources
(some of which can be out of date).

The only relevant resource for C API docs with practical examples for each API is 
currently is this website: https://silverhammermba.github.io/emberb/

However the author is sometimes unresponsive and the documentation on some APIs
is missing.

The extension.rdoc file in the ruby repo is not complete either.
There is almost no mention of various critical functions for things like string
encoding and hashes.

Therefore, I propose we maintain a full C API documentation divided into meaningful
sections and host this complete and 'official' documentation on ruby-doc.org website
such that it is directly picked up from the Ruby repo (the same way the current docs for
the Ruby core library are). We should at least aim to make it as complete and comprehensive
as the Python C API docs: https://docs.python.org/3/c-api/index.html

The other benefit of maintaining it this way is that users can easily see changes across
Ruby versions. Having good documentation for C APIs is critical for creating fast and
efficient scientific computing libraries for Ruby.

The C API docs can subdivided into the following sections. Please feel free to add to the list:

* Introduction
  - Include files
  - Interfacing extensions with Ruby gems using mkmf.
* Garbage Collection
* Basic Ruby functionality
  - Creating classes, constants, instance variables etc.
  - Method calls and constant lookup.
* Global Interpreter Lock
* Interfacing C structs with Ruby
* Interfaces to Ruby core classes
  - String
    - String encodings
  - Hash
  - Float
  - Integer
  - Symbol





-- 
https://bugs.ruby-lang.org/

Unsubscribe: <mailto:ruby-core-request / ruby-lang.org?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-core>