merge revision(s) 2304cfa4c08a347f4df4915f88fb062cb12e4eeb:

	Document MakeMakefile#append_cflags

	This method is at least 7 years old and is widely used in the wild.
	Since we need to support it, let's document it to make it discoverable.
	Add docs and move it out of the `# :stopdoc:` zone.
	---
	 lib/mkmf.rb | 25 +++++++++++++++----------
	 1 file changed, 15 insertions(+), 10 deletions(-)

1 files changed, 15 insertions, 10 deletions

diff --git a/lib/mkmf.rb b/lib/mkmf.rb
index 907c9dbcbc..6f9b8fd670 100644
--- a/lib/mkmf.rb
+++ b/lib/mkmf.rb
@@ -688,16 +688,6 @@ MSG
     try_compile(MAIN_DOES_NOTHING, flags, {:werror => true}.update(opts))
   end
 
-  def append_cflags(flags, *opts)
-    Array(flags).each do |flag|
-      if checking_for("whether #{flag} is accepted as CFLAGS") {
-           try_cflags(flag, *opts)
-         }
-        $CFLAGS << " " << flag
-      end
-    end
-  end
-
   def with_ldflags(flags)
     ldflags = $LDFLAGS
     $LDFLAGS = flags.dup
@@ -1032,6 +1022,21 @@ SRC
 
   # :startdoc:
 
+  # Check whether each given C compiler flag is acceptable and append it
+  # to <tt>$CFLAGS</tt> if so.
+  #
+  # [+flags+] a C compiler flag as a +String+ or an +Array+ of them
+  #
+  def append_cflags(flags, *opts)
+    Array(flags).each do |flag|
+      if checking_for("whether #{flag} is accepted as CFLAGS") {
+           try_cflags(flag, *opts)
+         }
+        $CFLAGS << " " << flag
+      end
+    end
+  end
+
   # Returns whether or not +macro+ is defined either in the common header
   # files or within any +headers+ you provide.
   #