From 0971b90d59dbc365e8f3d4e38b005a03cde70a21 Mon Sep 17 00:00:00 2001
From: Zachary Scott <zachary@zacharyscott.net>
Date: Thu, 31 May 2012 17:33:18 -0400
Subject: [PATCH] Migrate extconf.rb documentation from README.EXT to MakeMakefile

---
 README.EXT  |   97 +----------------------------------------------------------
 lib/mkmf.rb |   89 +++++++++++++++++++++++++++++++++++++++++++++++++----
 2 files changed, 83 insertions(+), 103 deletions(-)

diff --git a/README.EXT b/README.EXT
index 8368a94..ea5f5ef 100644
--- a/README.EXT
+++ b/README.EXT
@@ -1409,102 +1409,7 @@ passed to the given event hook function.
 
 Appendix C. Functions Available in extconf.rb
 
-These functions are available in extconf.rb:
-
- have_macro(macro, headers, opt)
-
-Checks whether macro is defined with header.  Returns true if the macro
-is defined.
-
- have_library(lib, func, opt)
-
-Checks whether the library exists, containing the specified function.
-Returns true if the library exists.
-
- find_library(lib, func, path...)
-
-Checks whether a library which contains the specified function exists in
-path.  Returns true if the library exists.
-
- have_func(func, headers, opt)
-
-Checks whether func exists with header.  Returns true if the function
-exists.  To check functions in an additional library, you need to
-check that library first using have_library().
-The func shall be either mere function name or function name with
-arguments.
-Example:
-    have_func("LONG2NUM(0)")
-
- have_var(var, header, opt)
-
-Checks whether var exists with header.  Returns true if the variable
-exists.  To check variables in an additional library, you need to
-check that library first using have_library().
-
- have_header(header, preheaders, opt)
-
-Checks whether header exists.  Returns true if the header file exists.
-
- find_header(header, path...)
-
-Checks whether header exists in path.  Returns true if the header file
-exists.
-
- have_struct_member(type, member, headers, opt)
-
-Checks whether type has member with header.  Returns true if the type
-is defined and has the member.
-
- have_type(type, headers, opt)
-
-Checks whether type is defined with header.  Returns true if the type
-is defined.
-
- check_sizeof(type, header)
-
-Checks the size of type in char with header.  Returns the size if the
-type is defined, otherwise nil.
-
- create_makefile(target)
-
-Generates the Makefile for the extension library.  If you don't invoke
-this method, the compilation will not be done.
-
- find_executable(bin, path)
-
-Finds command in path, which is File::PATH_SEPARATOR-separated list of
-directories.  If path is nil or omitted, environment variable PATH
-will be used.  Returns the path name of the command if it is found,
-otherwise nil.
-
- with_config(withval[, default=nil])
-
-Parses the command line options and returns the value specified by
---with-<withval>.
-
- enable_config(config, *defaults)
- disable_config(config, *defaults)
-
-Parses the command line options for boolean.  Returns true if
---enable-<config> is given, or false if --disable-<config> is given.
-Otherwise, yields defaults to the given block and returns the result
-if it is called with a block, or returns defaults.
-
- dir_config(target[, default_dir])
- dir_config(target[, default_include, default_lib])
-
-Parses the command line options and adds the directories specified by
---with-<target>-dir, --with-<target>-include, and/or --with-<target>-lib
-to $CFLAGS and/or $LDFLAGS.  --with-<target>-dir=/path is equivalent to
---with-<target>-include=/path/include --with-<target>-lib=/path/lib.
-Returns an array of the added directories ([include_dir, lib_dir]).
-
- pkg_config(pkg)
-
-Obtains the information for pkg by pkg-config command.  The actual
-command name can be overridden by --with-pkg-config command line
-option.
+See MakeMakefile for functions that are available to extconf.rb
 
 /*
  * Local variables:
diff --git a/lib/mkmf.rb b/lib/mkmf.rb
index c42bab9..f418152 100644
--- a/lib/mkmf.rb
+++ b/lib/mkmf.rb
@@ -873,6 +873,10 @@ SRC
 
   # :startdoc:
 
+  #
+  # :call-seq:
+  #   have_macro(macro, headers, opt)
+  #
   # Returns whether or not +macro+ is defined either in the common header
   # files or within any +headers+ you provide.
   #
@@ -884,8 +888,12 @@ SRC
     end
   end
 
+  #
+  # :call-seq:
+  #   have_library(lib, func, opt)
+  #
   # Returns whether or not the given entry point +func+ can be found within
-  # +lib+.  If +func+ is nil, the <code>main()</code> entry point is used by
+  # +lib+.  If +func+ is +nil+, the <code>main()</code> entry point is used by
   # default.  If found, it adds the library to list of libraries to be used
   # when linking your extension.
   #
@@ -913,9 +921,13 @@ SRC
     end
   end
 
+  #
+  # :call-seq:
+  #   find_library(lib, func, paths...)
+  #
   # Returns whether or not the entry point +func+ can be found within the
   # library +lib+ in one of the +paths+ specified, where +paths+ is an array
-  # of strings.  If +func+ is nil , then the <code>main()</code> function is
+  # of strings.  If +func+ is +nil+ , then the <code>main()</code> function is
   # used as the entry point.
   #
   # If +lib+ is found, then the path it was found on is added to the list of
@@ -943,12 +955,20 @@ SRC
     end
   end
 
+  #
+  # :call-seq:
+  #   have_func(func, headers, opt)
+  #
   # Returns whether or not the function +func+ can be found in the common
   # header files, or within any +headers+ that you provide.  If found, a macro
   # is passed as a preprocessor constant to the compiler using the function
   # name, in uppercase, prepended with +HAVE_+.
   #
-  # For example, if <code>have_func('foo')</code> returned true, then the
+  # To check functions in an additional library, you need to check that
+  # library first using <code>have_library()</code>.  The +func+ shall be
+  # either mere function name or function name with arguments.
+  #
+  # For example, if <code>have_func('foo')</code> returned +true+, then the
   # +HAVE_FOO+ preprocessor macro would be passed to the compiler.
   #
   def have_func(func, headers = nil, opt = "", &b)
@@ -962,11 +982,18 @@ SRC
     end
   end
 
+  #
+  # :call-seq:
+  #   have_var(var, header, opt)
+  #
   # Returns whether or not the variable +var+ can be found in the common
   # header files, or within any +headers+ that you provide.  If found, a macro
   # is passed as a preprocessor constant to the compiler using the variable
   # name, in uppercase, prepended with +HAVE_+.
   #
+  # To check variables in an additional library, you need to check that
+  # library first using <code>have_library()</code>.
+  #
   # For example, if <code>have_var('foo')</code> returned true, then the
   # +HAVE_FOO+ preprocessor macro would be passed to the compiler.
   #
@@ -981,6 +1008,10 @@ SRC
     end
   end
 
+  #
+  # :call-seq:
+  #   have_header(header, preheaders, opt)
+  #
   # Returns whether or not the given +header+ file can be found on your system.
   # If found, a macro is passed as a preprocessor constant to the compiler
   # using the header file name, in uppercase, prepended with +HAVE_+.
@@ -1020,6 +1051,10 @@ SRC
     end
   end
 
+  #
+  # :call-seq:
+  #   find_header(header, paths...)
+  #
   # Instructs mkmf to search for the given +header+ in any of the +paths+
   # provided, and returns whether or not it was found in those paths.
   #
@@ -1048,6 +1083,10 @@ SRC
     end
   end
 
+  #
+  # :call-seq:
+  #   have_struct_member(type, member, headers, opt)
+  #
   # Returns whether or not the struct of type +type+ contains +member+.  If
   # it does not, or the struct type can't be found, then false is returned.
   # You may optionally specify additional +headers+ in which to look for the
@@ -1098,6 +1137,10 @@ SRC
     end
   end
 
+  #
+  # :call-seq:
+  #   have_type(type, headers, opt)
+  #
   # Returns whether or not the static type +type+ is defined.  You may
   # optionally pass additional +headers+ to check against in addition to the
   # common header files.
@@ -1202,6 +1245,10 @@ SRC
 
   # :startdoc:
 
+  #
+  # :call-seq:
+  #   check_sizeof(type, header)
+  #
   # Returns the size of the given +type+.  You may optionally specify
   # additional +headers+ to search in for the +type+.
   #
@@ -1451,6 +1498,10 @@ SRC
 
   # :startdoc:
 
+  #
+  # :call-seq:
+  #   find_executable(bin, path)
+  #
   # Searches for the executable +bin+ on +path+.  The default path is your
   # +PATH+ environment variable. If that isn't defined, it will resort to
   # searching /usr/local/bin, /usr/ucb, /usr/bin and /bin.
@@ -1481,9 +1532,13 @@ SRC
 
   # :startdoc:
 
+  #
+  # :call-seq:
+  #   with_config(withval[, default=nil])
+  #
   # Tests for the presence of a <tt>--with-</tt>_config_ or
-  # <tt>--without-</tt>_config_ option.  Returns true if the with option is
-  # given, false if the without option is given, and the default value
+  # <tt>--without-</tt>_config_ option.  Returns +true+ if the with option is
+  # given, +false+ if the without option is given, and the default value
   # otherwise.
   #
   # This can be useful for adding custom definitions, such as debug
@@ -1516,9 +1571,13 @@ SRC
     end
   end
 
+  #
+  # :call-seq:
+  #   enable_config(config, *defaults)
+  #
   # Tests for the presence of an <tt>--enable-</tt>_config_ or
-  # <tt>--disable-</tt>_config_ option. Returns true if the enable option is
-  # given, false if the disable option is given, and the default value
+  # <tt>--disable-</tt>_config_ option. Returns +true+ if the enable option is
+  # given, +false+ if the disable option is given, and the default value
   # otherwise.
   #
   # This can be useful for adding custom definitions, such as debug
@@ -1591,6 +1650,11 @@ SRC
     $extconf_h = header
   end
 
+  #
+  # :call-seq:
+  #   dir_config(target[, default_dir])
+  #   dir_config(target[, default_include, default_lib])
+  #
   # Sets a +target+ name that the user can then use to configure various
   # "with" options with on the command line by using that name.  For example,
   # if the target is set to "foo", then the user could use the
@@ -1639,8 +1703,15 @@ SRC
 
   # :stopdoc:
 
+  #
+  # :call-seq:
+  #   pkg_config(pkg)
+  #
   # Handles meta information about installed libraries. Uses your platform's
   # pkg-config program if it has one.
+  #
+  # The actual command name can be overridden by
+  # <code>--with-pkg-config</code> command line option.
   def pkg_config(pkg)
     if pkgconfig = with_config("#{pkg}-config") and find_executable0(pkgconfig)
       # iff package specific config command is given
@@ -1902,6 +1973,10 @@ RULES
     depout
   end
 
+  #
+  # :call-seq:
+  #   create_makefile(target)
+  #
   # Generates the Makefile for your extension, passing along any options and
   # preprocessor constants that you may have generated through other methods.
   #
-- 
1.7.4.1

