Project

General

Profile

Feature #15074

Create 'official' C API documentation on ruby-doc.org

Added by v0dro (Sameer Deshmukh) over 1 year ago. Updated over 1 year ago.

Status:
Open
Priority:
Normal
Assignee:
-
Target version:
-
[ruby-core:88848]

Description

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

Also available in: Atom PDF