[WIP] Release Notes

In these notes we collected informations for you to update the
JerryScript from 1.0 to 2.0.

JerryScript-DCO-1.0-Signed-off-by: Istvan Miklos [email protected]

Author: Istvan Miklos

docs/00.RELEASE-NOTES.md

@@ -0,0 +1,372 @@
+# Release Notes
+
+In these notes we gather all the information for you to update the JerryScript from 1.0 to 2.0.
+
+We have changed API functions and removed some legacy macros/headers.
+Changes are all documented below you can see them in the before and after code snippets.
+If you are looking for something that has been deleted we have a list further down.
+As for the new functions we have a list of them, for more information please checkout the [API reference](02.API-REFERENCE.md).
+
+## Error manipulating functions
+
+These functions have been reworked in most cases. Every function got a second argument which can call a `jerry_release_value` for the input API value.
+
+### jerry_value_set_abort_flag
+
+This function was replaced with  [`jerry_create_abort_from_value`](02.API-REFERENCE.md#jerry_create_abort_from_value).
+
+**Before**
+
+```c
+{
+  jerry_value_t value;
+  ... // create or acquire value
+
+  jerry_value_set_abort_flag (&value);
+  jerry_release_value (value);
+}
+```
+
+**After**
+
+```c
+{
+  jerry_value_t value;
+  ... // create or acquire value
+
+  jerry_value_t abort = jerry_create_abort_from_value (value, true);
+  // using the 'value' variable after release is invalid
+
+  jerry_release_value (abort);
+}
+```
+
+- OR
+
+```c
+{
+  jerry_value_t value;
+  ... // create or acquire value
+
+  jerry_value_t abort = jerry_create_abort_from_value (value, false);
+  // both 'abort' and 'value' can be used and must be released when they are no longer needed
+
+  jerry_release_value (abort);
+  jerry_release_value (value);
+}
+```
+
+### jerry_value_has_abort_flag
+
+This function was renamed to  [`jerry_value_is_abort`](02.API-REFERENCE.md#jerry_value_is_abort).
+
+**Before**
+
+```c
+{
+  jerry_value_t value;
+  ... // create or acquire value
+
+  jerry_value_set_abort_flag (&value);
+  if (jerry_value_has_abort_flag (value))
+  {
+    ...
+  }
+  jerry_release_value (value);
+}
+```
+
+**After**
+
+```c
+{
+  jerry_value_t value;
+  ... // create or acquire value
+
+  jerry_value_t abort = jerry_create_abort_from_value (value, true);
+  if (jerry_value_is_abort (abort))
+  {
+    ...
+  }
+  jerry_release_value (abort);
+}
+```
+
+### jerry_value_set_error_flag
+
+This function was replaced with  [`jerry_create_error_from_value`](02.API-REFERENCE.md#jerry_create_error_from_value).
+
+**Before**
+
+```c
+{
+  jerry_value_t value;
+  ... // create or acquire value
+
+  jerry_value_set_error_flag (&value);
+  jerry_release_value (value);
+}
+```
+
+**After**
+
+```c
+{
+  jerry_value_t value;
+  ... // create or acquire value
+
+  jerry_value_t error = jerry_create_error_from_value (value, true);
+  // using the 'value' variable after release is invalid
+
+  jerry_release_value (error);
+}
+```
+
+- OR
+
+```c
+{
+  jerry_value_t value;
+  ... // create or acquire value
+
+  jerry_value_t error = jerry_create_error_from_value (value, false);
+  // both 'error' and 'value' can be used and must be released when they are no longer needed
+
+  jerry_release_value (error);
+  jerry_release_value (value);
+}
+```
+
+### jerry_value_has_error_flag
+
+This function was renamed to  [`jerry_value_is_error`](02.API-REFERENCE.md#jerry_value_is_error).
+
+**Before**
+
+```c
+{
+  jerry_value_t value;
+  ... // create or acquire value
+
+  jerry_value_set_error_flag (&value);
+  if (jerry_value_has_error_flag (value))
+  {
+    ...
+  }
+  jerry_release_value (value);
+}
+```
+
+**After**
+
+```c
+{
+  jerry_value_t value;
+  ... // create or acquire value
+
+  jerry_value_t error = jerry_create_error_from_value (value, true);
+  if (jerry_value_is_error (error))
+  {
+    ...
+  }
+  jerry_release_value (error);
+}
+```
+
+### jerry_value_clear_error_flag AND jerry_get_value_without_error_flag
+
+These functions was merged into [`jerry_get_value_from_error`](02.API-REFERENCE.md#jerry_get_value_from_error).
+
+**Before**
+
+```c
+{
+  jerry_value_t value;
+  ... // create or acquire value
+
+  jerry_value_set_error_flag (&value);
+  jerry_value_clear_error_flag (&value);
+  // or
+  jerry_value_t real_value = jerry_get_value_without_error_flag (value);
+
+  jerry_release_value (value);
+  jerry_release_value (real_value);
+}
+```
+
+**After**
+
+```c
+{
+  jerry_value_t value;
+  ... // create or acquire value
+
+  jerry_value_t error = jerry_create_error_from_value (value, true);
+  jerry_value_t real_value = jerry_get_value_from_error (error, true);
+
+  jerry_release_value (real_value);
+}
+```
+
+## Snapshot generating API
+
+### jerry_parse_and_save_snapshot
+
+This function was replaced with [`jerry_generate_snapshot`](02.API-REFERENCE.md#jerry_generate_snapshot).
+
+**Before**
+
+```c
+{
+  static uint32_t global_mode_snapshot_buffer[256];
+  const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();";
+
+  size_t global_mode_snapshot_size =
+  jerry_parse_and_save_snapshot (code_to_snapshot_p,
+                                 strlen ((const char *) code_to_snapshot_p),
+                                 true,
+                                 false,
+                                 global_mode_snapshot_buffer,
+                                 sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
+  jerry_cleanup ();
+}
+```
+
+**After**
+
+```c
+{
+  static uint32_t global_mode_snapshot_buffer[256];
+  const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();";
+
+  jerry_value_t generate_result;
+  generate_result = jerry_generate_snapshot (NULL,
+                                             0,
+                                             code_to_snapshot_p,
+                                             strlen ((const char *) code_to_snapshot_p),
+                                             global_mode_snapshot_buffer,
+                                             sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
+  size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
+  jerry_release_value (generate_result);
+  jerry_cleanup ();
+}
+```
+
+### jerry_parse_and_save_function_snapshot
+
+This function was replaced with [`jerry_generate_function_snapshot`](02.API-REFERENCE.md#jerry_parse_and_save_function_snapshot).
+
+**Before**
+
+```c
+{
+  const jerry_char_t *args_p = (const jerry_char_t *) "a, b";
+  const jerry_char_t *src_p = (const jerry_char_t *) "return a + b;";
+
+  size_t func_snapshot_size =
+  jerry_parse_and_save_function_snapshot (src_p,
+                                          strlen ((const char *) src_p),
+                                          args_p,
+                                          strlen ((const char *) args_p),
+                                          false,
+                                          func_snapshot_buffer,
+                                          sizeof (func_snapshot_buffer) / sizeof (uint32_t));
+
+  jerry_cleanup ();
+}
+```
+
+**After**
+
+```c
+{
+  const jerry_char_t *args_p = (const jerry_char_t *) "a, b";
+  const jerry_char_t *src_p = (const jerry_char_t *) "return a + b;";
+
+  jerry_value_t generate_result;
+  generate_result = jerry_generate_function_snapshot (NULL,
+                                                      0,
+                                                      src_p,
+                                                      strlen ((const char *) src_p),
+                                                      args_p,
+                                                      strlen ((const char *) args_p),
+                                                      0,
+                                                      func_snapshot_buffer,
+                                                      sizeof (func_snapshot_buffer) / sizeof (uint32_t));
+
+  size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
+  jerry_release_value (generate_result)
+  jerry_cleanup ();
+}
+```
+
+## Removed/renamed
+
+***Removed legacy headers***
+
+- `jerry-api.h`
+- `jerry-port.h`
+- `jerry-internal.h`
+
+***Renamed headers***
+
+- `jerry-port.h` to `jerrysctipt-port.h`
+
+***Removed API functions***
+
+- `jerry_get_memory_limits`
+
+***Removed unused configuration macros***
+
+- `CONFIG_MEM_DATA_LIMIT_MINUS_HEAP_SIZE`
+- `CONFIG_MEM_STACK_LIMIT`
+- `CONFIG_VM_STACK_FRAME_INLINED_VALUES_NUMBER`
+- `CONFIG_ECMA_GLOBAL_ENVIRONMENT_DECLARATIVE`
+
+# New API functions
+
+In this section we are introducing new API functions.
+
+***Feature***
+
+- [`jerry_is_feature_enabled`](02.API-REFERENCE.md#jerry_is_feature_enabled)
+
+***Parse***
+
+- [`jerry_parse_and_save_literals`](02.API-REFERENCE.md#jerry_parse_and_save_literals)
+
+***Promise***
+
+- [`jerry_run_all_enqueued_jobs`](02.API-REFERENCE.md#jerry_run_all_enqueued_jobs)
+
+***String***
+
+- [`jerry_substring_to_utf8_char_buffer`](02.API-REFERENCE.md#jerry_substring_to_utf8_char_buffer)
+- [`jerry_get_utf8_string_size`](02.API-REFERENCE.md#jerry_get_utf8_string_size)
+- [`jerry_get_utf8_string_length`](02.API-REFERENCE.md#jerry_get_utf8_string_length)
+- [`jerry_create_string_from_utf8`](02.API-REFERENCE.md#jerry_create_string_from_utf8)
+- [`jerry_create_string_sz_from_utf8`](02.API-REFERENCE.md#jerry_create_string_sz_from_utf8)
+
+***Number***
+
+- [`jerry_create_number_infinity`](02.API-REFERENCE.md#jerry_create_number_infinity)
+- [`jerry_create_number_nan`](02.API-REFERENCE.md#jerry_create_number_nan)
+
+***Error manipulating***
+
+- [`jerry_get_error_type`](02.API-REFERENCE.md#jerry_get_error_type)
+
+***TypedArray***
+
+- [`jerry_create_typedarray`](02.API-REFERENCE.md#jerry_create_typedarray)
+- [`jerry_create_typedarray_for_arraybuffer`](02.API-REFERENCE.md#jerry_create_typedarray_for_arraybuffer)
+- [`jerry_create_typedarray_for_arraybuffer_sz`](02.API-REFERENCE.md#jerry_create_typedarray_for_arraybuffer_sz)
+- [`jerry_get_typedarray_type`](02.API-REFERENCE.md#jerry_get_typedarray_type)
+- [`jerry_get_typedarray_length`](02.API-REFERENCE.md#jerry_get_typedarray_length)
+- [`jerry_get_typedarray_buffer`](02.API-REFERENCE.md#jerry_get_typedarray_buffer)
+- [`jerry_value_is_typedarray`](02.API-REFERENCE.md#jerry_value_is_typedarray)
+
+***ArrayBuffer***
+
+- [`jerry_create_arraybuffer_external`](02.API-REFERENCE.md#jerry_create_arraybuffer_external)
+- [`jerry_get_arraybuffer_pointer`](02.API-REFERENCE.md#jerry_get_arraybuffer_pointer)