extension.rdoc: add document title

* doc/extension.rdoc, doc/extension.ja.rdoc: [DOC]
  add title and adapt subheading levels.

* doc/extension.rdoc: [DOC] fix subheading level of section
  about "Ruby Constants That Can Be Accessed From C".

* doc/extension.ja.rdoc: [DOC] add missing subheading.

[ruby-core:79590] [Bug #13229]
Author:    Marcus Stollsteimer <[email protected]>

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@57665 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 72 insertions, 70 deletions

diff --git a/doc/extension.rdoc b/doc/extension.rdoc
index d5426ec3fe..303c7a2c32 100644
--- a/doc/extension.rdoc
+++ b/doc/extension.rdoc
@@ -1,8 +1,10 @@
 # extension.rdoc -  -*- RDoc -*- created at: Mon Aug  7 16:45:54 JST 1995
 
+= Creating Extension Libraries for Ruby
+
 This document explains how to make extension libraries for Ruby.
 
-= Basic Knowledge
+== Basic Knowledge
 
 In C, variables have types and data do not have types.  In contrast,
 Ruby variables do not have a static type, and data themselves have
@@ -18,7 +20,7 @@ To retrieve C data from a VALUE, you need to:
 
 Converting to the wrong data type may cause serious problems.
 
-== Data Types
+=== Data Types
 
 The Ruby interpreter has the following data types:
 
@@ -52,7 +54,7 @@ T_ZOMBIE    :: object awaiting finalization
 
 Most of the types are represented by C structures.
 
-== Check Data Type of the VALUE
+=== Check Data Type of the VALUE
 
 The macro TYPE() defined in ruby.h shows the data type of the VALUE.
 TYPE() returns the constant number T_XXXX described above.  To handle
@@ -86,7 +88,7 @@ There are also faster check macros for fixnums and nil.
   FIXNUM_P(obj)
   NIL_P(obj)
 
-== Convert VALUE into C Data
+=== Convert VALUE into C Data
 
 The data for type T_NIL, T_FALSE, T_TRUE are nil, false, true
 respectively.  They are singletons for the data type.
@@ -139,7 +141,7 @@ Notice: Do not change the value of the structure directly, unless you
 are responsible for the result.  This ends up being the cause of
 interesting bugs.
 
-== Convert C Data into VALUE
+=== Convert C Data into VALUE
 
 To convert C data to Ruby values:
 
@@ -165,14 +167,14 @@ INT2NUM() :: for arbitrary sized integers.
 INT2NUM() converts an integer into a Bignum if it is out of the FIXNUM
 range, but is a bit slower.
 
-== Manipulating Ruby Data
+=== Manipulating Ruby Data
 
 As I already mentioned, it is not recommended to modify an object's
 internal structure.  To manipulate objects, use the functions supplied
 by the Ruby interpreter. Some (not all) of the useful functions are
 listed below:
 
-=== String Functions
+==== String Functions
 
 rb_str_new(const char *ptr, long len) ::
 
@@ -273,7 +275,7 @@ rb_str_set_len(VALUE str, long len) ::
   up to len bytes, regardless RSTRING_LEN(str).  len must not exceed
   the capacity of str.
 
-=== Array Functions
+==== Array Functions
 
 rb_ary_new() ::
 
@@ -330,9 +332,9 @@ rb_ary_cat(VALUE ary, const VALUE *ptr, long len) ::
 
   Appends len elements of objects from ptr to the array.
 
-= Extending Ruby with C
+== Extending Ruby with C
 
-== Adding New Features to Ruby
+=== Adding New Features to Ruby
 
 You can add new features (classes, methods, etc.) to the Ruby
 interpreter.  Ruby provides APIs for defining the following things:
@@ -341,7 +343,7 @@ interpreter.  Ruby provides APIs for defining the following things:
 - Methods, Singleton Methods
 - Constants
 
-=== Class and Module Definition
+==== Class and Module Definition
 
 To define a class or module, use the functions below:
 
@@ -356,7 +358,7 @@ To define nested classes or modules, use the functions below:
   VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super)
   VALUE rb_define_module_under(VALUE outer, const char *name)
 
-=== Method and Singleton Method Definition
+==== Method and Singleton Method Definition
 
 To define methods or singleton methods, use these functions:
 
@@ -449,7 +451,7 @@ available), you can use:
 
   VALUE rb_current_receiver(void)
 
-=== Constant Definition
+==== Constant Definition
 
 We have 2 functions to define constants:
 
@@ -459,11 +461,11 @@ We have 2 functions to define constants:
 The former is to define a constant under specified class/module.  The
 latter is to define a global constant.
 
-== Use Ruby Features from C
+=== Use Ruby Features from C
 
 There are several ways to invoke Ruby's features from C code.
 
-=== Evaluate Ruby Programs in a String
+==== Evaluate Ruby Programs in a String
 
 The easiest way to use Ruby's functionality from a C program is to
 evaluate the string as Ruby program.  This function will do the job:
@@ -481,7 +483,7 @@ function:
 It returns nil when an error occurred. Moreover, *state is zero if str was
 successfully evaluated, or nonzero otherwise.
 
-=== ID or Symbol
+==== ID or Symbol
 
 You can invoke methods directly, without parsing the string.  First I
 need to explain about ID.  ID is the integer number to represent
@@ -532,7 +534,7 @@ and to convert Ruby Symbol object to ID, use
 
   ID SYM2ID(VALUE symbol)
 
-=== Invoke Ruby Method from C
+==== Invoke Ruby Method from C
 
 To invoke methods directly, you can use the function below
 
@@ -541,7 +543,7 @@ To invoke methods directly, you can use the function below
 This function invokes a method on the recv, with the method name
 specified by the symbol mid.
 
-=== Accessing the Variables and Constants
+==== Accessing the Variables and Constants
 
 You can access class variables and instance variables using access
 functions.  Also, global variables can be shared between both
@@ -560,7 +562,7 @@ To access the constants of the class/module:
 
 See also Constant Definition above.
 
-= Information Sharing Between Ruby and C
+== Information Sharing Between Ruby and C
 
 === Ruby Constants That Can Be Accessed From C
 
@@ -576,7 +578,7 @@ Qnil ::
 
   Ruby nil in C scope.
 
-== Global Variables Shared Between C and Ruby
+=== Global Variables Shared Between C and Ruby
 
 Information can be shared between the two environments using shared global
 variables.  To define them, you can use functions listed below:
@@ -618,7 +620,7 @@ The prototypes of the getter and setter functions are as follows:
   VALUE (*getter)(ID id);
   void (*setter)(VALUE val, ID id);
 
-== Encapsulate C Data into a Ruby Object
+=== Encapsulate C Data into a Ruby Object
 
 Sometimes you need to expose your struct in the C world as a Ruby
 object.
@@ -632,7 +634,7 @@ In the future version of Ruby, it is possible old macros will not
 work.
 ++
 
-=== C struct to Ruby object
+==== C struct to Ruby object
 
 You can convert sval, a pointer to your struct, into a Ruby object
 with the next macro.
@@ -735,7 +737,7 @@ Arguments klass and data_type work like their counterparts in
 TypedData_Wrap_Struct().  A pointer to the allocated structure will
 be assigned to sval, which should be a pointer of the type specified.
 
-=== Ruby object to C struct
+==== Ruby object to C struct
 
 To retrieve the C pointer from the Data object, use the macro
 Data_Get_Struct().
@@ -746,23 +748,23 @@ A pointer to the structure will be assigned to the variable sval.
 
 See the example below for details.
 
-= Example - Creating the dbm Extension
+== Example - Creating the dbm Extension
 
 OK, here's the example of making an extension library.  This is the
 extension to access DBMs.  The full source is included in the ext/
 directory in the Ruby's source tree.
 
-== Make the Directory
+=== Make the Directory
 
   % mkdir ext/dbm
 
 Make a directory for the extension library under ext directory.
 
-== Design the Library
+=== Design the Library
 
 You need to design the library features, before making it.
 
-== Write the C Code
+=== Write the C Code
 
 You need to write C code for your extension library.  If your library
 has only one source file, choosing ``LIBRARY.c'' as a file name is
@@ -887,7 +889,7 @@ but are not exported to the Ruby world.  You need to protect them by
 
   void rb_global_variable(VALUE *var)
 
-== Prepare extconf.rb
+=== Prepare extconf.rb
 
 If the file named extconf.rb exists, it will be executed to generate
 Makefile.
@@ -936,7 +938,7 @@ If a compilation condition is not fulfilled, you should not call
 ``create_makefile''.  The Makefile will not be generated, compilation will
 not be done.
 
-== Prepare Depend (Optional)
+=== Prepare Depend (Optional)
 
 If the file named depend exists, Makefile will include that file to
 check dependencies.  You can make this file by invoking
@@ -945,7 +947,7 @@ check dependencies.  You can make this file by invoking
 
 It's harmless.  Prepare it.
 
-== Generate Makefile
+=== Generate Makefile
 
 Try generating the Makefile by:
 
@@ -960,7 +962,7 @@ You don't need this step if you put the extension library under the ext
 directory of the ruby source tree.  In that case, compilation of the
 interpreter will do this step for you.
 
-== Run make
+=== Run make
 
 Type
 
@@ -969,21 +971,21 @@ Type
 to compile your extension.  You don't need this step either if you have
 put the extension library under the ext directory of the ruby source tree.
 
-== Debug
+=== Debug
 
 You may need to rb_debug the extension.  Extensions can be linked
 statically by adding the directory name in the ext/Setup file so that
 you can inspect the extension with the debugger.
 
-== Done! Now You Have the Extension Library
+=== Done! Now You Have the Extension Library
 
 You can do anything you want with your library.  The author of Ruby
 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 Source Files Overview
 
-== Ruby Language Core
+=== Ruby Language Core
 
 class.c    :: classes and modules
 error.c    :: exception classes and exception mechanism
@@ -992,14 +994,14 @@ load.c     :: library loading
 object.c   :: objects
 variable.c :: variables and constants
 
-== Ruby Syntax Parser
+=== Ruby Syntax Parser
 
 parse.y       :: grammar definition
 parse.c       :: automatically generated from parse.y
 defs/keywords :: reserved keywords
 lex.c         :: automatically generated from keywords
 
-== Ruby Evaluator (a.k.a. YARV)
+=== Ruby Evaluator (a.k.a. YARV)
 
   compile.c
   eval.c
@@ -1025,7 +1027,7 @@ lex.c         :: automatically generated from keywords
     -> opt*.inc            : automatically generated
     -> vm.inc              : automatically generated
 
-== Regular Expression Engine (Oniguruma)
+=== Regular Expression Engine (Oniguruma)
 
   regex.c
   regcomp.c
@@ -1035,7 +1037,7 @@ lex.c         :: automatically generated from keywords
   regparse.c
   regsyntax.c
 
-== Utility Functions
+=== Utility Functions
 
 debug.c    :: debug symbols for C debugger
 dln.c      :: dynamic loading
@@ -1043,7 +1045,7 @@ st.c       :: general purpose hash table
 strftime.c :: formatting times
 util.c     :: misc utilities
 
-== Ruby Interpreter Implementation
+=== Ruby Interpreter Implementation
 
   dmyext.c
   dmydln.c
@@ -1057,7 +1059,7 @@ util.c     :: misc utilities
   gem_prelude.rb
   prelude.rb
 
-== Class Library
+=== Class Library
 
 array.c      :: Array
 bignum.c     :: Bignum
@@ -1089,22 +1091,22 @@ time.c       :: Time
 defs/known_errors.def :: Errno::* exception classes
 -> known_errors.inc   :: automatically generated
 
-== Multilingualization
+=== Multilingualization
 
 encoding.c  :: Encoding
 transcode.c :: Encoding::Converter
 enc/*.c     :: encoding classes
 enc/trans/* :: codepoint mapping tables
 
-== goruby Interpreter Implementation
+=== goruby Interpreter Implementation
 
   goruby.c
   golf_prelude.rb     : goruby specific libraries.
     -> golf_prelude.c : automatically generated
 
-= Appendix B. Ruby Extension API Reference
+== Appendix B. Ruby Extension API Reference
 
-== Types
+=== Types
 
 VALUE ::
 
@@ -1112,7 +1114,7 @@ VALUE ::
   such as struct RString, etc.  To refer the values in structures, use
   casting macros like RSTRING(obj).
 
-== Variables and Constants
+=== Variables and Constants
 
 Qnil ::
 
@@ -1126,7 +1128,7 @@ Qfalse ::
 
   false object
 
-== C Pointer Wrapping
+=== C Pointer Wrapping
 
 Data_Wrap_Struct(VALUE klass, void (*mark)(), void (*free)(), void *sval) ::
 
@@ -1146,7 +1148,7 @@ Data_Get_Struct(data, type, sval) ::
   This macro retrieves the pointer value from DATA, and assigns it to
   the variable sval.
 
-== Checking Data Types
+=== Checking Data Types
 
 RB_TYPE_P(value, type) ::
 
@@ -1180,7 +1182,7 @@ SafeStringValue(value) ::
 
   Checks that +value+ is a String and is not tainted
 
-== Data Type Conversion
+=== Data Type Conversion
 
 FIX2INT(value), INT2FIX(i) ::
 
@@ -1264,7 +1266,7 @@ rb_str_new2(s) ::
 
   char * -> String
 
-== Defining Classes and Modules
+=== Defining Classes and Modules
 
 VALUE rb_define_class(const char *name, VALUE super) ::
 
@@ -1291,7 +1293,7 @@ void rb_extend_object(VALUE object, VALUE module) ::
 
   Extend the object with the module's attributes.
 
-== Defining Global Variables
+=== Defining Global Variables
 
 void rb_define_variable(const char *name, VALUE *var) ::
 
@@ -1332,7 +1334,7 @@ void rb_global_variable(VALUE *var) ::
   GC requires C global variables which hold Ruby values to be marked.
   rb_global_variable tells GC to protect these variables.
 
-== Constant Definition
+=== Constant Definition
 
 void rb_define_const(VALUE klass, const char *name, VALUE val) ::
 
@@ -1344,7 +1346,7 @@ void rb_define_global_const(const char *name, VALUE val) ::
 
     rb_define_const(rb_cObject, name, val)
 
-== Method Definition
+=== Method Definition
 
 rb_define_method(VALUE klass, const char *name, VALUE (*func)(ANYARGS), int argc) ::
 
@@ -1447,7 +1449,7 @@ VALUE rb_extract_keywords(VALUE *original_hash) ::
   non-symbol keys, then they are copied to another hash and the new hash
   is stored through +original_hash+, else 0 is stored.
 
-== Invoking Ruby method
+=== Invoking Ruby method
 
 VALUE rb_funcall(VALUE recv, ID mid, int narg, ...) ::
 
@@ -1485,7 +1487,7 @@ int rb_respond_to(VALUE obj, ID id) ::
 
   Returns true if the object responds to the message specified by id.
 
-== Instance Variables
+=== Instance Variables
 
 VALUE rb_iv_get(VALUE obj, const char *name) ::
 
@@ -1496,7 +1498,7 @@ VALUE rb_iv_set(VALUE obj, const char *name, VALUE val) ::
 
   Sets the value of the instance variable.
 
-== Control Structure
+=== Control Structure
 
 VALUE rb_block_call(VALUE recv, ID mid, int argc, VALUE * argv, VALUE (*func) (ANYARGS), VALUE data2) ::
 
@@ -1562,7 +1564,7 @@ void rb_iter_break_value(VALUE value) ::
   return the given argument value.  This function never return to the
   caller.
 
-== Exceptions and Errors
+=== Exceptions and Errors
 
 void rb_warn(const char *fmt, ...) ::
 
@@ -1597,7 +1599,7 @@ Note: In the format string, "%"PRIsVALUE can be used for Object#to_s
 must be a VALUE).  Since it conflicts with "%i", for integers in
 format strings, use "%d".
 
-== Initialize and Start the Interpreter
+=== Initialize and Start the Interpreter
 
 The embedding API functions are below (not needed for extension libraries):
 
@@ -1622,7 +1624,7 @@ void ruby_script(char *name) ::
 
   Specifies the name of the script ($0).
 
-== Hooks for the Interpreter Events
+=== Hooks for the Interpreter Events
 
 void rb_add_event_hook(rb_event_hook_func_t func, rb_event_flag_t events, VALUE data) ::
 
@@ -1652,7 +1654,7 @@ int rb_remove_event_hook(rb_event_hook_func_t func) ::
 
   Removes the specified hook function.
 
-== Memory usage
+=== Memory usage
 
 void rb_gc_adjust_memory_usage(ssize_t diff) ::
 
@@ -1664,7 +1666,7 @@ void rb_gc_adjust_memory_usage(ssize_t diff) ::
   is decreased; a memory block is freed or a block is reallocated as
   smaller size.  This function may trigger the GC.
 
-== Macros for Compatibility
+=== Macros for Compatibility
 
 Some macros to check API compatibilities are available by default.
 
@@ -1704,11 +1706,11 @@ RB_EVENT_HOOKS_HAVE_CALLBACK_DATA ::
   Means that rb_add_event_hook() takes the third argument `data', to be
   passed to the given event hook function.
 
-= Appendix C. Functions available for use in extconf.rb
+== Appendix C. Functions available for use in extconf.rb
 
 See documentation for {mkmf}[rdoc-ref:MakeMakefile].
 
-= Appendix D. Generational GC
+== Appendix D. Generational GC
 
 Ruby 2.1 introduced a generational garbage collector (called RGenGC).
 RGenGC (mostly) keeps compatibility.
@@ -1722,7 +1724,7 @@ If your library adheres to the following tips, performance can
 be further improved. Especially, the "Don't touch pointers directly" section is
 important.
 
-== Incompatibility
+=== Incompatibility
 
 You can't write RBASIC(obj)->klass field directly because it is const
 value now.
@@ -1741,13 +1743,13 @@ VALUE rb_obj_reveal(VALUE obj, VALUE klass) ::
   Reset RBasic::klass to be klass.
   We expect the `klass' is hidden class by rb_obj_hide().
 
-== Write barriers
+=== Write barriers
 
 RGenGC doesn't require write barriers to support generational GC.
 However, caring about write barrier can improve the performance of
 RGenGC. Please check the following tips.
 
-=== Don't touch pointers directly
+==== Don't touch pointers directly
 
 In MRI (include/ruby/ruby.h), some macros to acquire pointers to the
 internal data structures are supported such as RARRAY_PTR(),
@@ -1756,7 +1758,7 @@ RSTRUCT_PTR() and so on.
 DO NOT USE THESE MACROS and instead use the corresponding C-APIs such as
 rb_ary_aref(), rb_ary_store() and so on.
 
-=== Consider whether to insert write barriers
+==== Consider whether to insert write barriers
 
 You don't need to care about write barriers if you only use built-in
 types.
@@ -1778,7 +1780,7 @@ introduce critical bugs. And inserting write barriers has several areas
 of overhead. Basically we don't recommend you insert write barriers.
 Please carefully consider the risks.
 
-=== Combine with built-in types
+==== Combine with built-in types
 
 Please consider utilizing built-in types. Most built-in types support
 write barrier, so you can use them to avoid manually inserting write
@@ -1793,7 +1795,7 @@ references.
 With use of such techniques, you don't need to insert write barriers
 anymore.
 
-=== Insert write barriers
+==== Insert write barriers
 
 \[AGAIN] Inserting write barriers is a very difficult hack, and it is
 easy to introduce critical bugs. And inserting write barriers has
@@ -1807,7 +1809,7 @@ available in include/ruby/ruby.h. An example is available in iseq.c.
 For a complete guide for RGenGC and write barriers, please refer to
 <https://bugs.ruby-lang.org/projects/ruby-trunk/wiki/RGenGC>.
 
-= Appendix E. RB_GC_GUARD to protect from premature GC
+== Appendix E. RB_GC_GUARD to protect from premature GC
 
 C Ruby currently uses conservative garbage collection, thus VALUE
 variables must remain visible on the stack or registers to ensure any