[DOC] mention macros for public headers

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引数として

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
+Only <tt>$repo_root/include/ruby/*.h</tt> whose corresponding macros
-by C extensions. Files under <tt>$repo_root/include/ruby/internal</tt>
+are defined in the <tt>$repo_root/include/ruby.h</tt> header are
-should not be <tt>#include</tt>-d directly.
+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