[DOC] Describe append_{c,cpp,ld}flags

doc/extension.ja.rdoc

@@ -1757,6 +1757,14 @@ check_sizeof(type, header) ::
   `SIZEOF_{TYPE}` を定義し，そのサイズを返す．定義されていな
   いときはnilを返す．
 
+append_cppflags(array-of-flags[, opt])
+append_cflags(array-of-flags[, opt])
+append_ldflags(array-of-flags[, opt])
+
+  各flagが使用可能であれば，それぞれ$CPPFLAGS, $CFLAGS,
+  $LDFLAGSに追加する．コンパイラのフラグには移植性がないので，
+  変数に直接追加せずこれらを使うことが望ましい．
+
 create_makefile(target[, target_prefix]) ::
 
   拡張ライブラリ用のMakefileを生成する．この関数を呼ばなけれ

doc/extension.rdoc

@@ -956,6 +956,9 @@ need to put
 at the top of the file.  You can use the functions below to check
 various conditions.
 
+  append_cppflags(array-of-flags[, opt]): append each flag to $CPPFLAGS if usable
+  append_cflags(array-of-flags[, opt]): append each flag to $CFLAGS if usable
+  append_ldflags(array-of-flags[, opt]): append each flag to $LDFLAGS if usable
   have_macro(macro[, headers[, opt]]): check whether macro is defined
   have_library(lib[, func[, headers[, opt]]]): check whether library containing function exists
   find_library(lib[, func, *paths]): find library from paths
@@ -984,6 +987,10 @@ The value of the variables below will affect the Makefile.
   $LDFLAGS: included in LDFLAGS make variable (such as -L)
   $objs: list of object file names
 
+Compiler/linker flags are not portable usually, you should use
++append_cppflags+, +append_cpflags+ and +append_ldflags+ respectively
+instead of appending the above variables directly.
+
 Normally, the object files list is automatically generated by searching
 source files, but you must define them explicitly if any sources will
 be generated while building.