Update documentation for jerry string to buffer function with suggestions to use substring. (#2174) (#2174)

In some use cases, you want to reliably copy jerry strings to buffer, even if it doesn't fit target buffer, but is acceptable to lose some bytes. In those cases, the documentation will now suggest using the substring function as an alternative instead.

JerryScript-DCO-1.0-Signed-off-by: Brian Khuu mofosyne@gmail.com

docs/02.API-REFERENCE.md

@@ -1612,13 +1612,13 @@ jerry_value_set_abort_flag (jerry_value_t *value_p);
 If the input value is an error value, then return a new reference to its referenced value.
 Otherwise, return a new reference to the value itself.
 
-*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) 
+*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value)
 when it is no longer needed.
 
 **Prototype**
 
 ```c
-jerry_value_t 
+jerry_value_t
 jerry_get_value_without_error_flag (jerry_value_t value)
 ```
 
@@ -1630,12 +1630,12 @@ jerry_get_value_without_error_flag (jerry_value_t value)
 {
   jerry_value_t value;
   ... // create or acquire value
-  
+
   jerry_value_set_error_flag (&value);
-  
+
   jerry_value_t real_value = jerry_get_value_without_error_flag (value);
-  ... // process the real_value. Different from `jerry_value_clear_error_flag`, 
-      // the error `value` will not be automatically released after calling 
+  ... // process the real_value. Different from `jerry_value_clear_error_flag`,
+      // the error `value` will not be automatically released after calling
       // `jerry_get_value_without_error_flag`.
 
   jerry_release_value (value);
@@ -1905,6 +1905,12 @@ enough for the whole string.
 *Note*: Does not put '\0' to the end of string, the return value identifies
 the number of valid bytes in the output buffer.
 
+*Note*: If the size of the string in jerry value is larger than the size of the
+target buffer, the copy will fail. To copy a substring the
+[jerry_substring_to_char_buffer](#jerry_substring_to_char_buffer) API function
+is recommended instead.
+
+
 **Prototype**
 
 ```c
@@ -1940,6 +1946,7 @@ jerry_string_to_char_buffer (const jerry_value_t value,
 - [jerry_create_string](#jerry_create_string)
 - [jerry_get_string_size](#jerry_get_string_size)
 - [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string)
+- [jerry_substring_to_char_buffer](#jerry_substring_to_char_buffer)
 
 
 ## jerry_string_to_utf8_char_buffer
@@ -1954,6 +1961,11 @@ large enough for the whole string.
 *Note*: Does not put '\0' to the end of string, the return value identifies
 the number of valid bytes in the output buffer.
 
+*Note*: If the size of the string in jerry value is larger than the size of the
+target buffer, the copy will fail. To copy a substring the
+[jerry_substring_to_utf8_char_buffer](#jerry_substring_to_utf8_char_buffer)
+API function is recommended instead.
+
 **Prototype**
 
 ```c
@@ -1989,6 +2001,7 @@ jerry_string_to_utf8_char_buffer (const jerry_value_t value,
 - [jerry_create_string_from_utf8](#jerry_create_string_from_utf8)
 - [jerry_get_utf8_string_size](#jerry_get_utf8_string_size)
 - [jerry_is_valid_utf8_string](#jerry_is_valid_utf8_string)
+- [jerry_substring_to_utf8_char_buffer](#jerry_substring_to_utf8_char_buffer)
 
 
 ## jerry_substring_to_char_buffer

jerry-core/api/jerry.c

@@ -1521,6 +1521,11 @@ jerry_get_utf8_string_length (const jerry_value_t value) /**< input string */
  *      Returns 0, if the value parameter is not a string or
  *      the buffer is not large enough for the whole string.
  *
+ * Note:
+ *      If the size of the string in jerry value is larger than the size of the
+ *      target buffer, the copy will fail.
+ *      To copy substring use jerry_substring_to_char_buffer() instead.
+ *
  * @return number of bytes, actually copied to the buffer.
  */
 jerry_size_t
@@ -1557,6 +1562,11 @@ jerry_string_to_char_buffer (const jerry_value_t value, /**< input string value
  *      Returns 0, if the value parameter is not a string or the buffer
  *      is not large enough for the whole string.
  *
+ * Note:
+ *      If the size of the string in jerry value is larger than the size of the
+ *      target buffer, the copy will fail.
+ *      To copy a substring use jerry_substring_to_utf8_char_buffer() instead.
+ *
  * @return number of bytes copied to the buffer.
  */
 jerry_size_t