Merge pull request #3035 from iij/pr-yard-mrb_str_to_cstr

YARD doc for mrb_str_to_cstr.

1 files changed, 13 insertions, 1 deletions

diff --git a/include/mruby/string.h b/include/mruby/string.h
index c049a72c7..6e4a73c19 100644
--- a/include/mruby/string.h
+++ b/include/mruby/string.h
@@ -175,7 +175,19 @@ MRB_API mrb_value mrb_str_append(mrb_state *mrb, mrb_value str, mrb_value str2);
 MRB_API int mrb_str_cmp(mrb_state *mrb, mrb_value str1, mrb_value str2);
 
 /*
- * Returns a C string from a Ruby string.
+ * Returns a newly allocated C string from a Ruby string.
+ * This is an utility function to pass a Ruby string to C library functions.
+ *
+ * - Returned string does not contain any NUL characters (but terminator).
+ * - It raises an ArgumentError exception if Ruby string contains
+ *   NUL characters.
+ * - Retured string will be freed automatically on next GC.
+ * - Caller can modify returned string without affecting Ruby string
+ *   (e.g. it can be used for mkstemp(3)).
+ *
+ * @param [mrb_state *] mrb The current mruby state.
+ * @param [mrb_value] str Ruby string. Must be an instance of String.
+ * @return [char *] A newly allocated C string.
  */
 MRB_API char *mrb_str_to_cstr(mrb_state *mrb, mrb_value str);