Improve the JSON C API (#3943)

* Added more details into documentation.
* Moved the C unit-test into its own file.
* Added extra test cases.
* Extended the API reference documentation with doctests.

JerryScript-DCO-1.0-Signed-off-by: Peter Gal pgal.usz@partner.samsung.com

docs/02.API-REFERENCE.md

@@ -8572,7 +8572,11 @@ jerry_get_typedarray_buffer (jerry_value_t value,
 
 **Summary**
 
-Returns the same result as `JSON.parse` ecmascript function.
+Parses a JSON string creating a JavaScript value. The behaviour is equivalent with
+the "JSON.parse(string)" JS call.
+
+*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+is no longer needed.
 
 **Prototype**
 
@@ -8582,24 +8586,38 @@ jerry_json_parse (const jerry_char_t *string_p,
                   jerry_size_t string_size);
 ```
 
-- `string_p` - a JSON string
-- `string_size` - size of the string
+- `string_p` - pointer to a JSON string.
+- `string_size` - size of the string.
 - return
-  - jerry_value_t containing the same as json.parse()
-  - jerry_value_t containing error massage
+  - `jerry_value_t` containing a JavaScript value.
+  - Error value in case of any parse error.
 
 *New in version 2.0*.
 
 **Example**
 
+[doctest]: # ()
+
 ```c
+#include "jerryscript.h"
+
+int
+main (void)
 {
+  /* Initialize engine */
+  jerry_init (JERRY_INIT_EMPTY);
+
   const jerry_char_t data[] = "{\"name\": \"John\", \"age\": 5}";
-  jerry_value_t parsed_json = jerry_json_parse (data, sizeof (data) - 1);
+  jerry_value_t obj = jerry_json_parse (data, sizeof (data) - 1);
 
-  // parsed_json now conatins all data stored in data_in_json
+  /* "obj" now conatins and object created from the "data" JSON string. */
 
-  jerry_release_value (parsed_json);
+  jerry_release_value (obj);
+
+  /* Cleanup engine */
+  jerry_cleanup ();
+
+  return 0;
 }
 ```
 
@@ -8607,37 +8625,58 @@ jerry_json_parse (const jerry_char_t *string_p,
 
 **Summary**
 
-Returns the same value as `JSON.stringify` ecmascript function.
+Create a JSON string value from a JavaScript value. The behaviour is equivalent with
+the "JSON.stringify(input_value)" JS call.
+
+*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_json_stringify (const jerry_value_t object_to_stringify);
+jerry_json_stringify (const jerry_value_t input_value);
 ```
 
-- `object_to_stringify` - a jerry_value_t object to stringify
+- `input_value` - a `jerry_value_t` to stringify.
 - return
-  - jerry_value_t containing the same as json.stringify()
-  - jerry_value_t containing error massage
+  - `jerry_value_t` containing a JSON string.
+  - Error value in case of any stringification error.
 
 *New in version 2.0*.
 
 **Example**
 
+[doctest]: # ()
+
 ```c
+#include "jerryscript.h"
+
+int
+main (void)
 {
+  /* Initialize engine */
+  jerry_init (JERRY_INIT_EMPTY);
+
   jerry_value_t obj = jerry_create_object ();
-  jerry_value_t key = jerry_create_string ((const jerry_char_t *) "name");
-  jerry_value_t value = jerry_create_string ((const jerry_char_t *) "John");
-  jerry_release_value (jerry_set_property (obj, key, value));
+  {
+    jerry_value_t key = jerry_create_string ((const jerry_char_t *) "name");
+    jerry_value_t value = jerry_create_string ((const jerry_char_t *) "John");
+    jerry_release_value (jerry_set_property (obj, key, value));
+    jerry_release_value (key);
+    jerry_release_value (value);
+  }
+
   jerry_value_t stringified = jerry_json_stringify (obj);
 
-  //stringified now contains a json formated string
+  /* "stringified" now contains a JSON string */
 
-  jerry_release_value (obj);
-  jerry_release_value (key);
-  jerry_release_value (value);
   jerry_release_value (stringified);
+  jerry_release_value (obj);
+
+  /* Cleanup engine */
+  jerry_cleanup ();
+
+  return 0;
 }
 ```