From: shevegen@... Date: 2018-09-05T11:00:47+00:00 Subject: [ruby-core:88857] [Ruby trunk Feature#15074] Create 'official' C API documentation on ruby-doc.org 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: