From 529c98ab900e88679a21c891600b42a076486661 Mon Sep 17 00:00:00 2001
From: Nobuyoshi Nakada <nobu@ruby-lang.org>
Date: Wed, 4 May 2022 01:22:49 +0900
Subject: [PATCH] [DOC] mention macros for public headers

---
 doc/extension.ja.rdoc | 17 +++++++++++++++++
 doc/extension.rdoc    |  9 ++++++---
 2 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/doc/extension.ja.rdoc b/doc/extension.ja.rdoc
index dbe814560e..93f5753cd1 100644
--- a/doc/extension.ja.rdoc
+++ b/doc/extension.ja.rdoc
@@ -1066,6 +1066,20 @@ Rubyのソースはいくつかに分類することが出来ます．このう
 ています．これらのソースは今までの説明でほとんど理解できると
 思います．
 
+=== Rubyのヘッダファイル
+
+<tt>$repo_root/include/ruby</tt>以下はすべて<tt>make
+install</tt>でインストールされます．拡張ライブラリからは，
+<tt>#include <ruby.h></tt>でインクルードする必要があります．
++rbimpl_+，+RBIMPL_+のプレフィックスが付いた実装の詳細のため
+のシンボルを除き，すべてのシンボルは公開APIです．
+
+拡張ライブラリで直接インクルードできるのは，
+<tt>$repo_root/include/ruby/*.h</tt>のうち，対応する
+<tt>HAVE_RUBY_*_H</tt>マクロが
+<tt>$repo_root/include/ruby.h</tt>ヘッダーで定義されているも
+のです．
+
 === Ruby言語のコア
 
 class.c    :: クラスとモジュール
@@ -1681,6 +1695,9 @@ HAVE_RUBY_*_H ::
   を意味する．たとえば，HAVE_RUBY_ST_H が定義されている場合は
   単なる st.h ではなく ruby/st.h を使用する．
 
+  これらのマクロに対応するヘッダーファイルは，拡張ライブラリ
+  から直接インクルードしてもよい．
+
 RB_EVENT_HOOKS_HAVE_CALLBACK_DATA ::
 
   rb_add_event_hook() がフック関数に渡す data を第3引数として
diff --git a/doc/extension.rdoc b/doc/extension.rdoc
index 01bbcd816b..ad9ae641d2 100644
--- a/doc/extension.rdoc
+++ b/doc/extension.rdoc
@@ -1055,9 +1055,9 @@ 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.
+Only <tt>$repo_root/include/ruby/*.h</tt> whose corresponding macros
+are defined in the <tt>$repo_root/include/ruby.h</tt> header are
+allowed to be <tt>#include</tt>-d by C extensions.
 
 Header files under <tt>$repo_root/internal/</tt> or directly under the
 root <tt>$repo_root/*.h</tt> are not make-installed.
@@ -1932,6 +1932,9 @@ HAVE_RUBY_*_H ::
   instance, when HAVE_RUBY_ST_H is defined you should use ruby/st.h not
   mere st.h.
 
+  Header files corresponding to these macros may be <tt>#include</tt>
+  directly from extension libraries.
+
 RB_EVENT_HOOKS_HAVE_CALLBACK_DATA ::
 
   Means that rb_add_event_hook() takes the third argument `data', to be