https://git.ruby-lang.org/ruby.git/commit/?id=fff058a8d6

From fff058a8d6c2e5d7c3529484a1c9a636dbf66dc2 Mon Sep 17 00:00:00 2001
From: Lars Kanis <lars@g...>
Date: Thu, 23 Sep 2021 17:06:57 +0200
Subject: Add description of ruby header files to extension.rdoc

---
 doc/extension.rdoc | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/doc/extension.rdoc b/doc/extension.rdoc
index 12cff6b4971..3bb00c154e8 100644
--- a/doc/extension.rdoc
+++ b/doc/extension.rdoc
@@ -830,6 +830,7 @@ the library. https://github.com/ruby/ruby/blob/trunk/doc/extension.rdoc#L830
 
 Here's the example of an initializing function.
 
+  #include <ruby.h>
   void
   Init_dbm(void)
   {
@@ -1051,7 +1052,24 @@ You can do anything you want with your library.  The author of Ruby https://github.com/ruby/ruby/blob/trunk/doc/extension.rdoc#L1052
 will not claim any restrictions on your code depending on the Ruby API.
 Feel free to use, modify, distribute or sell your program.
 
-== Appendix A. Ruby Source Files Overview
+== Appendix A. Ruby Header and Source Files Overview
+
+=== Ruby Header Files
+
+Everything under <tt>$repo_root/include/ruby</tt> is installed with
+<tt>make install</tt>.
+It should be included per <tt>#include <ruby.h></tt> from C extensions.
+All symbols are public API with the exception of symbols prefixed with
++rbimpl_+ or +RBIMPL_+. They are implementation details and shouldn't
+be used by C extensions.
+
+Only <tt>$repo_root/include/ruby/*.h</tt> are allowed to be <tt>#include</tt>-d
+by C extensions. Files under <tt>$repo_root/include/ruby/internal</tt>
+should not be <tt>#include</tt>-d directly.
+
+Header files under <tt>$repo_root/internal/</tt> or directly under the
+root <tt>$repo_root/*.h</tt> are not make-installed.
+They are internal headers with only internal APIs.
 
 === Ruby Language Core
 
-- 
cgit v1.2.1


--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/