Make sure that snapshot API return values are the same as in the docs (#2997)

The snapshot API docs describe that those functions returns error if
the related features are not enabled. Updated the return values to follow
the API documentation.

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

Author: galpeter

docs/02.API-REFERENCE.md

@@ -6505,8 +6505,12 @@ main (void)
 
 Generate snapshot from the specified source code.
 
-*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
-is no longer needed.
+*Notes*:
+- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+  is no longer needed.
+- This API depends on a build option (`JERRY_SNAPSHOT_SAVE`) and can be checked in runtime with
+  the `JERRY_FEATURE_SNAPSHOT_SAVE` feature enum value, see [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+  If the feature is not enabled the function will return an error.
 
 **Prototype**
 
@@ -6560,7 +6564,11 @@ main (void)
                                              global_mode_snapshot_buffer,
                                              sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
 
-  size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
+  if (!jerry_value_is_error (generate_result))
+  {
+    size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
+  }
+
   jerry_release_value (generate_result);
 
   jerry_cleanup ();
@@ -6586,8 +6594,12 @@ with the given arguments.
 The function arguments and function body are
 passed as separated arguments.
 
-*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
-is no longer needed.
+*Notes*:
+- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+  is no longer needed.
+- This API depends on a build option (`JERRY_SNAPSHOT_SAVE`) and can be checked in runtime with
+  the `JERRY_FEATURE_SNAPSHOT_SAVE` feature enum value, see [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+  If the feature is not enabled the function will return an error.
 
 **Prototype**
 
@@ -6648,7 +6660,11 @@ main (void)
                                                       func_snapshot_buffer,
                                                       sizeof (func_snapshot_buffer) / sizeof (uint32_t));
 
-  size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
+  if (!jerry_value_is_error (generate_result))
+  {
+    size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
+  }
+
   jerry_release_value (generate_result);
 
   jerry_cleanup ();
@@ -6670,8 +6686,12 @@ main (void)
 
 Execute snapshot from the specified buffer.
 
-*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
-is no longer needed.
+*Notes*:
+- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+  is no longer needed.
+- This API depends on a build option (`JERRY_SNAPSHOT_EXEC`) and can be checked in runtime with
+  the `JERRY_FEATURE_SNAPSHOT_EXEC` feature enum value, see [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+  If the feature is not enabled the function will return an error.
 
 **Prototype**
 
@@ -6683,13 +6703,13 @@ jerry_exec_snapshot (const uint32_t *snapshot_p,
                      uint32_t exec_snapshot_opts);
 ```
 
-- `snapshot_p` - pointer to snapshot
-- `snapshot_size` - size of snapshot in bytes
-- `func_index` - index of executed function
+- `snapshot_p` - pointer to snapshot.
+- `snapshot_size` - size of snapshot in bytes.
+- `func_index` - index of executed function.
 - `exec_snapshot_opts` - any combination of [jerry_exec_snapshot_opts_t](#jerry_exec_snapshot_opts_t) flags.
 - return value
-  - result of bytecode, if run was successful
-  - thrown error, otherwise
+  - result of bytecode, if run was successful.
+  - thrown error, otherwise (an error is reported if the snapshot execution feature is not enabled).
 
 *Changed in version 2.0*: Added `func_index` and `exec_snapshot_opts` arguments. Removed the `copy_bytecode` last argument.
 
@@ -6716,6 +6736,7 @@ main (void)
                                              0,
                                              global_mode_snapshot_buffer,
                                              sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
+  // generate_result should be checked if it is an error or not
 
   size_t global_mode_snapshot_size = (size_t) jerry_get_number_value (generate_result);
   jerry_release_value (generate_result);
@@ -6728,6 +6749,9 @@ main (void)
                                            global_mode_snapshot_size,
                                            0,
                                            0);
+
+  // check the `res` value for error and process the result.
+
   jerry_release_value (res);
 
   jerry_cleanup ();
@@ -6750,8 +6774,12 @@ Load the selected snapshot function from the specified buffer as a function obje
 
 The lexical environment of the loaded function is always the global lexical environment.
 
-*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
-is no longer needed.
+*Notes*:
+- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+  is no longer needed.
+- This API depends on a build option (`JERRY_SNAPSHOT_EXEC`) and can be checked in runtime with
+  the `JERRY_FEATURE_SNAPSHOT_EXEC` feature enum value, see [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+  If the feature is not enabled the function will return an error.
 
 **Prototype**
 
@@ -6846,6 +6874,11 @@ main (void)
 Collect the used literals from the given snapshot and save them into a buffer in list or C format.
 None of these literals are magic strings. In C format only valid identifiers are collected.
 
+*Note*:
+- This API depends on a build option (`JERRY_SNAPSHOT_SAVE`) and can be checked in runtime with
+  the `JERRY_FEATURE_SNAPSHOT_SAVE` feature enum value, see [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+  If the feature is not enabled the function will return zero.
+
 **Prototype**
 
 ```c

jerry-core/api/jerry-snapshot.c

@@ -881,7 +881,7 @@ jerry_generate_snapshot (const jerry_char_t *resource_name_p, /**< script resour
   JERRY_UNUSED (buffer_p);
   JERRY_UNUSED (buffer_size);
 
-  return 0;
+  return jerry_create_error (JERRY_ERROR_COMMON, (const jerry_char_t *) "Snapshot save is not supported.");
 #endif /* ENABLED (JERRY_SNAPSHOT_SAVE) */
 } /* jerry_generate_snapshot */
 
@@ -1032,7 +1032,7 @@ jerry_exec_snapshot (const uint32_t *snapshot_p, /**< snapshot */
   JERRY_UNUSED (func_index);
   JERRY_UNUSED (exec_snapshot_opts);
 
-  return ECMA_VALUE_FALSE;
+  return jerry_create_error (JERRY_ERROR_COMMON, (const jerry_char_t *) "Snapshot execution is not supported.");
 #endif /* ENABLED (JERRY_SNAPSHOT_EXEC) */
 } /* jerry_exec_snapshot */
 
@@ -1831,7 +1831,7 @@ jerry_generate_function_snapshot (const jerry_char_t *resource_name_p, /**< scri
   JERRY_UNUSED (buffer_p);
   JERRY_UNUSED (buffer_size);
 
-  return 0;
+  return jerry_create_error (JERRY_ERROR_COMMON, (const jerry_char_t *) "Snapshot save is not supported.");
 #endif /* ENABLED (JERRY_SNAPSHOT_SAVE) */
 } /* jerry_generate_function_snapshot */
 
@@ -1858,6 +1858,6 @@ jerry_load_function_snapshot (const uint32_t *function_snapshot_p, /**< snapshot
   JERRY_UNUSED (func_index);
   JERRY_UNUSED (exec_snapshot_opts);
 
-  return ECMA_VALUE_FALSE;
+  return jerry_create_error (JERRY_ERROR_COMMON, (const jerry_char_t *) "Snapshot execution is not supported.");
 #endif /* ENABLED (JERRY_SNAPSHOT_EXEC) */
 } /* jerry_load_function_snapshot */