Merge pull request #3183 from Mav7/mav7/docs

yard docs for string.h

1 files changed, 213 insertions, 2 deletions

diff --git a/include/mruby/string.h b/include/mruby/string.h
index b94c355fe..b66bc0dd1 100644
--- a/include/mruby/string.h
+++ b/include/mruby/string.h
@@ -88,35 +88,215 @@ mrb_int mrb_str_strlen(mrb_state*, struct RString*);
 
 void mrb_gc_free_str(mrb_state*, struct RString*);
 MRB_API void mrb_str_modify(mrb_state*, struct RString*);
+/*
+ * Appends self to other. Returns self as a concatnated string.
+ *
+ * 
+ *  Example:
+ *
+ *     !!!c
+ *     int
+ *     main(int argc, 
+ *          char **argv)
+ *     {
+ *       // Variable declarations.
+ *       mrb_value str1;
+ *       mrb_value str2;
+ *
+ *       mrb_state *mrb = mrb_open();
+ *       if (!mrb)
+ *       {
+ *          // handle error
+ *       }
+ *
+ *       // Creates new Ruby strings.
+ *       str1 = mrb_str_new_cstr(mrb, "abc");
+ *       str2 = mrb_str_new_cstr(mrb, "def");
+ *
+ *       // Concatnates str2 to str1.
+ *       mrb_str_concat(mrb, str1, str2);
+ *
+ *      // Prints new Concatnated Ruby string.
+ *      mrb_p(mrb, str1);
+ *
+ *      mrb_close(mrb);
+ *      return 0;
+ *    }
+ *
+ *
+ *  Result:
+ *
+ *     => "abcdef"
+ *
+ * @param [mrb_state] mrb The current mruby state.
+ * @param [mrb_value] self String to concatenate.
+ * @param [mrb_value] other String to append to self.
+ * @return [mrb_value] Returns a new String appending other to self.
+ */
 MRB_API void mrb_str_concat(mrb_state*, mrb_value, mrb_value);
 
 /*
  * Adds two strings together.
+ *
+ * 
+ *  Example:
+ *
+ *     !!!c
+ *     int
+ *     main(int argc, 
+ *          char **argv)
+ *     {
+ *       // Variable declarations.
+ *       mrb_value a;
+ *       mrb_value b;
+ *       mrb_value c;
+ *
+ *       mrb_state *mrb = mrb_open();
+ *       if (!mrb)
+ *       {
+ *          // handle error
+ *       }
+ *
+ *       // Creates two Ruby strings from the passed in C strings.
+ *       a = mrb_str_new_cstr(mrb, "abc");
+ *       b = mrb_str_new_cstr(mrb, "def");
+ *
+ *       // Prints both C strings.
+ *       mrb_p(mrb, a);
+ *       mrb_p(mrb, b);
+ *
+ *       // Concatnates both Ruby strings.
+ *       c = mrb_str_plus(mrb, a, b);
+ *
+ *      // Prints new Concatnated Ruby string.
+ *      mrb_p(mrb, c);
+ *
+ *      mrb_close(mrb);
+ *      return 0;
+ *    }
+ *
+ *
+ *  Result:
+ *
+ *     => "abc"  # First string
+ *     => "def"  # Second string
+ *     => "abcdef" # First & Second concatnated.
+ *
+ * @param [mrb_state] mrb The current mruby state.
+ * @param [mrb_value] a First string to concatenate.
+ * @param [mrb_value] b Second string to concatenate.
+ * @return [mrb_value] Returns a new String containing a concatenated to b.
  */
 MRB_API mrb_value mrb_str_plus(mrb_state*, mrb_value, mrb_value);
 
 /*
  * Converts pointer into a Ruby string.
+ *
+ * @param [mrb_state] mrb The current mruby state.
+ * @param [void*] p The pointer to convert to Ruby string.
+ * @return [mrb_value] Returns a new Ruby String.
  */
 MRB_API mrb_value mrb_ptr_to_str(mrb_state *, void*);
 
 /*
  * Returns an object as a Ruby string.
+ *
+ * @param [mrb_state] mrb The current mruby state.
+ * @param [mrb_value] obj An object to return as a Ruby string.
+ * @return [mrb_value] An object as a Ruby string.
  */
 MRB_API mrb_value mrb_obj_as_string(mrb_state *mrb, mrb_value obj);
 
 /*
- * Resizes the string's length.
+ * Resizes the string's length. Returns the amount of characters
+ * in the specified by len.
+ *
+ * Example:
+ *
+ *     !!!c
+ *     int
+ *     main(int argc, 
+ *          char **argv)
+ *     {
+ *         // Variable declaration.
+ *         mrb_value str;
+ *
+ *         mrb_state *mrb = mrb_open();
+ *         if (!mrb)
+ *         {
+ *            // handle error 
+ *         }
+ *         // Creates a new string.
+ *         str = mrb_str_new_cstr(mrb, "Hello, world!");
+ *         // Returns 5 characters of 
+ *         mrb_str_resize(mrb, str, 5);
+ *         mrb_p(mrb, str);
+ *
+ *         mrb_close(mrb);
+ *         return 0;
+ *      }
+ *
+ * Result:
+ *
+ *     => "Hello"
+ *
+ * @param [mrb_state] mrb The current mruby state.
+ * @param [mrb_value] str The Ruby string to resize.
+ * @param [mrb_value] len The length.
+ * @return [mrb_value] An object as a Ruby string.
  */
 MRB_API mrb_value mrb_str_resize(mrb_state *mrb, mrb_value str, mrb_int len);
 
 /*
  * Returns a sub string.
+ *
+ *  Example:
+ *
+ *     !!!c
+ *     int
+ *     main(int argc, 
+ *     char const **argv)
+ *     {
+ *       // Variable declarations.
+ *       mrb_value str1;
+ *       mrb_value str2;
+ *
+ *       mrb_state *mrb = mrb_open();
+ *       if (!mrb)
+ *       {
+ *         // handle error
+ *       }
+ *       // Creates new string.
+ *       str1 = mrb_str_new_cstr(mrb, "Hello, world!");
+ *       // Returns a sub-string within the range of 0..2
+ *       str2 = mrb_str_substr(mrb, str1, 0, 2);
+ *
+ *       // Prints sub-string.
+ *       mrb_p(mrb, str2);
+ *
+ *       mrb_close(mrb);
+ *       return 0;
+ *     }
+ *
+ *  Result:
+ *
+ *     => "He"
+ *
+ * @param [mrb_state] mrb The current mruby state.
+ * @param [mrb_value] str Ruby string.
+ * @param [mrb_int] beg The beginning point of the sub-string.
+ * @param [mrb_int] len The end point of the sub-string.
+ * @return [mrb_value] An object as a Ruby sub-string.
  */
 MRB_API mrb_value mrb_str_substr(mrb_state *mrb, mrb_value str, mrb_int beg, mrb_int len);
 
 /*
  * Returns a Ruby string type.
+ *
+ *
+ * @param [mrb_state] mrb The current mruby state.
+ * @param [mrb_value] str Ruby string.
+ * @return [mrb_value] A Ruby string.
  */
 MRB_API mrb_value mrb_string_type(mrb_state *mrb, mrb_value str);
 
@@ -125,15 +305,32 @@ MRB_API mrb_value mrb_str_buf_new(mrb_state *mrb, size_t capa);
 
 MRB_API const char *mrb_string_value_cstr(mrb_state *mrb, mrb_value *ptr);
 MRB_API const char *mrb_string_value_ptr(mrb_state *mrb, mrb_value str);
+/*
+ * Returns the length of the Ruby string.
+ *
+ *
+ * @param [mrb_state] mrb The current mruby state.
+ * @param [mrb_value] str Ruby string.
+ * @return [mrb_int] The length of the passed in Ruby string.
+ */
 MRB_API mrb_int mrb_string_value_len(mrb_state *mrb, mrb_value str);
 
 /*
  * Duplicates a string object.
+ *
+ *
+ * @param [mrb_state] mrb The current mruby state.
+ * @param [mrb_value] str Ruby string.
+ * @return [mrb_value] Duplicated Ruby string.
  */
 MRB_API mrb_value mrb_str_dup(mrb_state *mrb, mrb_value str);
 
 /*
- * Returns a symbol from a passed in string.
+ * Returns a symbol from a passed in Ruby string.
+ *
+ * @param [mrb_state] mrb The current mruby state.
+ * @param [mrb_value] self Ruby string.
+ * @return [mrb_value] A symbol.
  */
 MRB_API mrb_value mrb_str_intern(mrb_state *mrb, mrb_value self);
 
@@ -147,12 +344,22 @@ MRB_API mrb_value mrb_str_to_str(mrb_state *mrb, mrb_value str);
 
 /*
  * Returns true if the strings match and false if the strings don't match.
+ *
+ * @param [mrb_state] mrb The current mruby state.
+ * @param [mrb_value] str1 Ruby string to compare.
+ * @param [mrb_value] str2 Ruby string to compare.
+ * @return [mrb_value] boolean value.
  */
 MRB_API mrb_bool mrb_str_equal(mrb_state *mrb, mrb_value str1, mrb_value str2);
 
 /*
  * Returns a concated string comprised of a Ruby string and a C string.
  *
+ * @param [mrb_state] mrb The current mruby state.
+ * @param [mrb_value] str Ruby string.
+ * @param [const char *] ptr A C string.
+ * @param [size_t] len length of C string.
+ * @return [mrb_value] A Ruby string.
  * @see mrb_str_cat_cstr
  */
 MRB_API mrb_value mrb_str_cat(mrb_state *mrb, mrb_value str, const char *ptr, size_t len);
@@ -160,6 +367,10 @@ MRB_API mrb_value mrb_str_cat(mrb_state *mrb, mrb_value str, const char *ptr, si
 /*
  * Returns a concated string comprised of a Ruby string and a C string.
  *
+ * @param [mrb_state] mrb The current mruby state.
+ * @param [mrb_value] str Ruby string.
+ * @param [const char *] ptr A C string.
+ * @return [mrb_value] A Ruby string.
  * @see mrb_str_cat
  */
 MRB_API mrb_value mrb_str_cat_cstr(mrb_state *mrb, mrb_value str, const char *ptr);