Add missing info in API doc (#4733)

As a few methods were removed and replaced it is a good idea to describe
which method(s) can reproduce the same functionality. In addition add a
bit of extra comments for various methods/structs.

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

1 files changed, 56 insertions, 17 deletions

diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md
index 2e774955..a01f5da2 100644
--- a/docs/02.API-REFERENCE.md
+++ b/docs/02.API-REFERENCE.md
@@ -67,7 +67,9 @@ Enum that contains JerryScript **object** value types:
 
 *New in version 2.4*.
 
-*Changed in version [[NEXT_RELEASE]]*: Added `JERRY_OBJECT_TYPE_SCRIPT`, `JERRY_OBJECT_TYPE_MODULE` values.
+*Changed in version [[NEXT_RELEASE]]*: Added `JERRY_OBJECT_TYPE_MODULE_NAMESPACE`, `JERRY_OBJECT_TYPE_PROMISE`, `JERRY_OBJECT_TYPE_DATAVIEW`,
+                                       `JERRY_OBJECT_TYPE_ERROR`, `JERRY_OBJECT_TYPE_SHARED_ARRAYBUFFER`, `JERRY_OBJECT_TYPE_WEAKREF`,
+                                       `JERRY_OBJECT_TYPE_SCRIPT`, and `JERRY_OBJECT_TYPE_MODULE` values.
 
 ## jerry_function_type_t
 
@@ -180,7 +182,8 @@ Possible compile time enabled feature types:
 
 *Changed in version 2.4*: Added `JERRY_FEATURE_BIGINT`, `JERRY_FEATURE_REALM` values.
 
-*Changed in version [[NEXT_RELEASE]]*: Added `JERRY_FEATURE_GLOBAL_THIS`, `JERRY_FEATURE_PROMISE_CALLBACK`, `JERRY_FEATURE_MODULE` values.
+*Changed in version [[NEXT_RELEASE]]*: Added `JERRY_FEATURE_VM_THROW`, `JERRY_FEATURE_GLOBAL_THIS`,
+                                       `JERRY_FEATURE_PROMISE_CALLBACK`, and `JERRY_FEATURE_MODULE` values.
 
 ## jerry_container_type_t
 
@@ -243,13 +246,16 @@ Option bits for [jerry_parse_options_t](#jerry_parse_options_t).
  - JERRY_PARSE_NO_OPTS - No options passed
  - JERRY_PARSE_STRICT_MODE - Enable strict mode
  - JERRY_PARSE_MODULE - Parse source as an ECMAScript module
- - JERRY_PARSE_HAS_ARGUMENT_LIST - `argument_list` field is valid
+ - JERRY_PARSE_HAS_ARGUMENT_LIST - `argument_list` field is valid, this also means that function parsing will be done
  - JERRY_PARSE_HAS_RESOURCE - `resource_name` field is valid
  - JERRY_PARSE_HAS_START - `start_line` and `start_column` fields are valid
  - JERRY_PARSE_HAS_USER_VALUE - `user_value` field is valid
 
 *New in version [[NEXT_RELEASE]]*.
 
+Using both `JERRY_PARSE_MODULE` and `JERRY_PARSE_HAS_ARGUMENT_LIST` is an invalid combination and will result in
+an error during parsing.
+
 **See also**
 
 - [jerry_parse_options_t](#jerry_parse_options_t)
@@ -304,6 +310,7 @@ when the snapshot is generated and executed. Furthermore the
 `JERRY_SNAPSHOT_EXEC_COPY_DATA` option is not allowed.
 
 *New in version 2.0*.
+
 *Changed in version [[NEXT_RELEASE]]*: The `JERRY_SNAPSHOT_SAVE_STRICT` value is removed, `JERRY_PARSE_STRICT_MODE` should be used instead.
 
 ## jerry_exec_snapshot_opts_t
@@ -594,6 +601,11 @@ typedef struct
 } jerry_property_descriptor_t;
 ```
 
+*Changed in version [[NEXT_RELEASE]]*: The `is_value_defined`, `is_get_defined`, `is_set_defined`,
+                                       `is_writable_defined`, `is_writable`, `is_enumerable_defined`,
+                                       `is_enumerable`, `is_configurable_defined`, and `is_configurable`
+                                       fields are replaced by the `flags` field.
+
 **See also**
 
 - [jerry_property_descriptor_flags_t](#jerry_property_descriptor_flags_t)
@@ -686,7 +698,7 @@ typedef struct jerry_call_info_t
 } jerry_call_info_t;
 ```
 
-*New in version [[NEXT_RELEASE]]*.
+*New in version [[NEXT_RELEASE]]*. Contents of this struct replaces the `jerry_get_new_target` function.
 
 **See also**
 
@@ -1745,11 +1757,13 @@ jerry_parse (const jerry_char_t *source_p,
   - thrown error, otherwise
 
 *Changed in version 2.0*: Added `resource_name_p`, and `resource_name_length` arguments.
+
 *Changed in version [[NEXT_RELEASE]]*: The `resource_name_p`, `resource_name_length`, and `parse_opts` arguments are replaced by `options_p`.
+                                       This function replaces the `jerry_parse_function` method.
 
-**Example**
+**Example 1**
 
-[doctest]: # ()
+[doctest]: # (name="02.API-REFERENCE-parse-simple.c")
 
 ```c
 #include "jerryscript.h"
@@ -1772,10 +1786,30 @@ main (void)
   jerry_value_t parsed_code = jerry_parse (script, sizeof (script) - 1, &parse_options);
   jerry_release_value (parse_options.resource_name);
 
+  /* Run the "parsed_code" script with "jerry_run". */
+
   jerry_release_value (jerry_run (parsed_code));
   jerry_release_value (parsed_code);
 
-  /* Parsing a function. */
+  jerry_cleanup ();
+  return 0;
+}
+```
+
+**Example - function parsing**
+
+[doctest]: # (name="02.API-REFERENCE-parse-function.c")
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  /* Specifly the argument list to parse a function. */
+  jerry_parse_options_t parse_options;
   parse_options.options = JERRY_PARSE_HAS_ARGUMENT_LIST;
   parse_options.argument_list = jerry_create_string ((const jerry_char_t *) "a, b");
 
@@ -1783,15 +1817,20 @@ main (void)
   jerry_value_t parsed_function = jerry_parse (function_code, sizeof (function_code) - 1, &parse_options);
   jerry_release_value (parse_options.argument_list);
 
+  /* Use the "parsed_function" as a normal JavaScript function. */
+
   jerry_value_t args[] = {
     jerry_create_number (3),
     jerry_create_number (4),
   };
   jerry_size_t argc = sizeof (args) / sizeof (args[0]);
-  jerry_release_value (jerry_call_function (parsed_function,
-                                            jerry_create_undefined(),
-                                            args,
-                                            argc));
+  jerry_value_t call_result = jerry_call_function (parsed_function,
+                                                   jerry_create_undefined(),
+                                                   args,
+                                                   argc);
+
+  /* use the function result */
+  jerry_release_value (call_result);
   jerry_release_value (parsed_function);
 
   jerry_cleanup ();
@@ -2312,7 +2351,7 @@ jerry_value_is_true (const jerry_value_t value);
     - true, if the given `jerry_value_t` is true value
     - false, otherwise
 
-*New in version [[NEXT_RELEASE]]*.
+*New in version [[NEXT_RELEASE]]*. Replaces the `jerry_value_is_boolean` method.
 
 **Example**
 
@@ -2352,7 +2391,7 @@ jerry_value_is_false (const jerry_value_t value);
     - true, if the given `jerry_value_t` is false value
     - false, otherwise
 
-*New in version [[NEXT_RELEASE]]*.
+*New in version [[NEXT_RELEASE]]*. Replaces the `jerry_value_is_boolean` method.
 
 **Example**
 
@@ -6656,8 +6695,6 @@ jerry_create_shared_arraybuffer_external (const jerry_length_t size
 
 *New in version [[NEXT_RELEASE]]*.
 
-*Changed in version [[NEXT_RELEASE]]*: type of `free_cb` has been changed.
-
 **Example**
 
 ```c
@@ -9060,7 +9097,7 @@ jerry_get_own_property_descriptor (const jerry_value_t  obj_val,
 - `prop_desc_p` - pointer to property descriptor
 - return value
 
-*Changed in version [[NEXT_RELEASE]]*: return value is changed to `jerry_value_t`
+*Changed in version [[NEXT_RELEASE]]*: Return value type is changed to `jerry_value_t`.
 
 **Example**
 
@@ -10589,7 +10626,9 @@ jerry_generate_snapshot (jerry_value_t compiled_code,
 *Changed in version [[NEXT_RELEASE]]*: The `source_p`, `source_size`, `resource_name_p`,
                                        and `resource_name_length` arguments are replaced by `compiled_code`
                                        which should contain a compiled ECMAScript script / function.
-
+                                       The `jerry_generate_function_snapshot` is now removed and can be reproduced
+                                       by calling `jerry_parse` with function arguments and using this method
+                                       (see [jerry_exec_snapshot](#jerry_exec_snapshot)).
 **Example**
 
 [doctest]: # ()