YourWishes/jerryscript
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Correct the documentation

Browse Source 
- Fix some style issue, typos, and examples
- Follow the variable naming conventions
- Fix tables both in the project and on the webpage

JerryScript-DCO-1.0-Signed-off-by: Zsolt Borbély zsborbely.u-szeged@partner.samsung.com
This commit is contained in:
Zsolt Borbély
2016-08-24 12:52:02 +02:00
parent 48d5eee920
commit e93e32635f
7 changed files with 180 additions and 153 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/02.API-REFERENCE.md
+62 -48
View File
@@ -13,6 +13,7 @@ Enum that contains the following elements:
## jerry_error_t
Possible types of an error:
- JERRY_ERROR_COMMON - common error
- JERRY_ERROR_EVAL - eval error
- JERRY_ERROR_RANGE - range error
@@ -33,6 +34,18 @@ Jerry's char value
typedef uint8_t jerry_char_t;
```
## jerry_char_ptr_t
**Summary**
Pointer to an array of character values
**Prototype**
```c
typedef jerry_char_t *jerry_char_ptr_t;
```
## jerry_size_t
**Summary**
@@ -130,7 +143,7 @@ Type of an external function handler
**Prototype**
```c
typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_obj_p,
typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_obj,
const jerry_value_t this_val,
const jerry_value_t args_p[],
const jerry_length_t args_count);
@@ -157,7 +170,7 @@ Function type applied for each data property of an object
**Prototype**
```c
typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_name_p,
typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_name,
const jerry_value_t property_value,
void *user_data_p);
```
@@ -233,14 +246,14 @@ Registers an external magic string array.
```c
void
jerry_register_magic_strings (const jerry_char_ptr_t *ex_str_items,
jerry_register_magic_strings (const jerry_char_ptr_t *ex_str_items_p,
uint32_t count,
const jerry_length_t *str_lengths);
const jerry_length_t *str_lengths_p);
```
- `ex_str_items` - character arrays, representing external magic strings' contents
- `ex_str_items_p` - character arrays, representing external magic strings' contents
- `count` - number of the strings
- `str_lengths` - lengths of the strings
- `str_lengths_p` - lengths of the strings
**Example**
@@ -296,8 +309,8 @@ jerry_get_memory_limits (size_t *out_data_bss_brk_limit_p,
jerry_init (JERRY_INIT_EMPTY);
size_t stack_limit;
size_t data_dss_brk_limit;
jerry_get_memory_limits (&stack_limit, &data_dss_brk_limit);
size_t data_bss_brk_limit;
jerry_get_memory_limits (&stack_limit, &data_bss_brk_limit);
}
```
@@ -345,12 +358,12 @@ The simplest way to run JavaScript.
```c
bool
jerry_run_simple (const jerry_char_t *script_source,
jerry_run_simple (const jerry_char_t *script_source_p,
size_t script_source_size,
jerry_init_flag_t flags);
```
- `script_source` - source code, it must be a valid utf8 string.
- `script_source_p` - source code, it must be a valid utf8 string.
- `script_source_size` - size of source code buffer, in bytes.
- `jerry_init_flag_t` - combination of various engine configuration flags
- return value
@@ -407,7 +420,7 @@ jerry_parse (const jerry_char_t *source_p,
{
jerry_init (JERRY_INIT_EMPTY);
char script [] = "print ('Hello, World!');";
const jerry_char_t script[] = "print ('Hello, World!');";
size_t script_size = strlen ((const char *) script);
jerry_value_t parsed_code = jerry_parse (script, script_size, false);
@@ -426,7 +439,7 @@ jerry_parse (const jerry_char_t *source_p,
**Summary**
Run an EcmaScript function created by jerry_parse.
Run an EcmaScript function created by `jerry_parse`.
*Note*: The code should be previously parsed with `jerry_parse`.
@@ -434,7 +447,7 @@ Run an EcmaScript function created by jerry_parse.
```c
jerry_value_t
jerry_run (jerry_value_t func_val);
jerry_run (const jerry_value_t func_val);
```
- `func_val` - function to run
@@ -558,6 +571,8 @@ Functions to check the type of an API value ([jerry_value_t](#jerry_value_t)).
**Summary**
Returns whether the given `jerry_value_t` is an array.
**Prototype**
```c
@@ -1018,7 +1033,7 @@ Get raw data from API values.
**Summary**
Gets the raw bool value form a `jerry_value_t`.
Gets the raw bool value from a `jerry_value_t`.
**Prototype**
@@ -1118,7 +1133,7 @@ jerry_get_string_size (const jerry_value_t value);
```c
{
jerry_char_t char_array[] = "a string";
const jerry_char_t char_array[] = "a string";
jerry_value_t string = jerry_create_string (char_array);
jerry_size_t string_size = jerry_get_string_size (string);
@@ -1155,7 +1170,7 @@ jerry_get_string_length (const jerry_value_t value);
```c
{
jerry_char_t char_array[] = "a string";
const jerry_char_t char_array[] = "a string";
jerry_value_t string = jerry_create_string (char_array);
jerry_length_t string_length = jerry_get_string_length (string);
@@ -1255,7 +1270,7 @@ jerry_get_array_length (const jerry_value_t value);
# Converters of 'jerry_value_t'
Functions for convering API values to another value type.
Functions for converting API values to another value type.
## jerry_value_to_boolean
@@ -1429,7 +1444,7 @@ jerry_value_to_string (const jerry_value_t value);
- `value` - api value
- return value
- converted srting value, if success
- converted string value, if success
- thrown error, otherwise
**Example**
@@ -1451,7 +1466,7 @@ jerry_value_to_string (const jerry_value_t value);
- [jerry_value_to_primitive](#jerry_value_to_primitive)
# Aquire and release API values
# Acquire and release API values
## jerry_acquire_value
@@ -1620,7 +1635,7 @@ jerry_create_error (jerry_error_t error_type,
```c
{
jerry_value_t error_obj = jerry_create_error (JERRY_ERROR_TYPE,
(jerry_char_t * ) "error");
(const jerry_char_t *) "error");
... // usage of error_obj
@@ -1660,10 +1675,10 @@ jerry_create_error_sz (jerry_error_t error_type,
```c
{
jerry_char_t message[] = "error";
const jerry_char_t *message = "error";
jerry_value_t error_obj = jerry_create_error_sz (JERRY_ERROR_COMMON,
message,
strlen ((char *) message));
strlen ((const char *) message));
... // usage of error_obj
@@ -1696,10 +1711,10 @@ jerry_create_external_function (jerry_external_handler_t handler_p);
```c
static jerry_value_t
handler (const jerry_value_t function_obj_p,
const jerry_value_t this_p,
handler (const jerry_value_t function_obj,
const jerry_value_t this_val,
const jerry_value_t args_p[],
const uint16_t args_cnt)
const jerry_length_t args_cnt)
{
printf ("native handler called!\n");
@@ -1711,7 +1726,7 @@ handler (const jerry_value_t function_obj_p,
jerry_value_t glob_obj = jerry_get_global_object ();
// after this, script can invoke the native handler through "handler_field (1, 2, 3);"
jerry_value_t prop_name = jerry_create_string ((jerry_char_t *) "handler_field");
jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "handler_field");
jerry_set_property (glob_obj, prop_name, func_val);
jerry_release_value (prop_name);
@@ -1953,7 +1968,7 @@ jerry_create_string_sz (const jerry_char_t *str_p,
{
const jerry_char_t char_array[] = "a string";
jerry_value_t string_value = jerry_create_string_sz (char_array,
strlen ((char *) char_array));
strlen ((const char *) char_array));
... // usage of string_value
@@ -1971,7 +1986,7 @@ jerry_create_string_sz (const jerry_char_t *str_p,
**Summary**
Creates a jerry_value_t representing an undefined value.
Creates a `jerry_value_t` representing an undefined value.
**Prototype**
@@ -2026,7 +2041,7 @@ jerry_has_property (const jerry_value_t obj_val,
```c
{
jerry_value_t global_object = jerry_get_global_object ();
jerry_value_t prop_name = jerry_create_string ((jerry_char_t *) "handler_field");
jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "handler_field");
bool has_prop = jerry_has_property (global_object, prop_name);
@@ -2066,7 +2081,7 @@ jerry_has_own_property (const jerry_value_t obj_val,
```c
{
jerry_value_t global_object = jerry_get_global_object ();
jerry_value_t prop_name = jerry_create_string ((jerry_char_t *) "handler_field");
jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "handler_field");
bool has_prop = jerry_has_own_property (global_object, prop_name);
@@ -2106,7 +2121,7 @@ jerry_delete_property (const jerry_value_t obj_val,
```c
{
jerry_value_t global_object = jerry_get_global_object ();
jerry_value_t prop_name = jerry_create_string ((jerry_char_t *) "my_prop");
jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_prop");
jerry_delete_property (global_object, prop_name);
@@ -2187,7 +2202,7 @@ jerry_get_property_by_index (const jerry_value_t obj_val,
```
- `obj_val` - object value
- index - index number
- `index` - index number
- return value
- stored value on the specified index, if success
- thrown exception, otherwise.
@@ -2253,7 +2268,7 @@ jerry_set_property (const jerry_value_t obj_val,
... // create or acquire value to set
jerry_value_t glob_obj = jerry_get_global_object ();
jerry_value_t prop_name = jerry_create_string ((jerry_char_t *) "my_prop");
jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "my_prop");
jerry_set_property (glob_obj, prop_name, value_to_set);
@@ -2295,7 +2310,7 @@ jerry_set_property_by_index (const jerry_value_t obj_val,
```
- `obj_val` - object value
- index - index number
- `index` - index number
- `value_to_set` - value to set
- return value
- true, if field value was set successfully
@@ -2576,7 +2591,7 @@ is no longer needed.
jerry_value_t
jerry_construct_object (const jerry_value_t func_obj_val,
const jerry_value_t args_p[],
uint16_t args_count);
jerry_size_t args_count);
```
- `func_obj_val` - function object to call
@@ -2792,12 +2807,12 @@ Set native handle and an optional free callback for the specified object
```c
void
jerry_set_object_native_handle (const jerry_value_t obj_val,
uintptr_t handle,
uintptr_t handle_p,
jerry_object_free_callback_t freecb_p);
```
- `obj_val` - object value to set handle in
- `handle` - handle value
- `handle_p` - handle value
- `freecb_p` - pointer to "free" callback or NULL
**Example**
@@ -2840,14 +2855,13 @@ jerry_foreach_object_property (jerry_value_t obj_val,
```
- `obj_val` - object value
- `foreach_p` - foreach function, that will be apllied for each property
- `foreach_p` - foreach function, that will be applied for each property
- `user_data_p` - user data for foreach function
- return value
- true, if object fields traversal was performed successfully, i.e.:
- no unhandled exceptions were thrown in object fields traversal
- object fields traversal was stopped on callback that returned false
- false, otherwise, if getter of field threw a exception or unhandled exceptions were thrown
during traversal
- false, otherwise
**Example**
@@ -2900,13 +2914,13 @@ jerry_parse_and_save_snapshot (const jerry_char_t *source_p,
- `source_p` - script source, it must be a valid utf8 string.
- `source_size` - script source size, in bytes.
- `is_for_global` - snapshot would be executed as global (true) or eval (false).
- `is_strict` - stric mode
- `is_strict` - strict mode
- `buffer_p` - buffer to save snapshot to.
- `buffer_size` - the buffer's size.
- return value
- the size of snapshot, if it was generated succesfully (i.e. there are no syntax errors in source
code, buffer size is sufficient, and snapshot support is enabled in current configuration through
JERRY_ENABLE_SNAPSHOT)
JERRY_ENABLE_SNAPSHOT_SAVE)
- 0 otherwise.
**Example**
@@ -2916,10 +2930,10 @@ jerry_parse_and_save_snapshot (const jerry_char_t *source_p,
jerry_init (JERRY_INIT_EMPTY);
static uint8_t global_mode_snapshot_buffer[1024];
const char *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();";
const jerry_char_t *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();";
size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot ((jerry_char_t *) code_to_snapshot_p,
strlen (code_to_snapshot_p),
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,
@@ -2970,11 +2984,11 @@ jerry_exec_snapshot (const void *snapshot_p,
{
jerry_value_t res;
static uint8_t global_mode_snapshot_buffer[1024];
const char *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();";
const jerry_char_t *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();";
jerry_init (JERRY_INIT_EMPTY);
size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot ((jerry_char_t *) code_to_snapshot_p,
strlen (code_to_snapshot_p),
size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot (code_to_snapshot_p,
strlen ((const char *) code_to_snapshot_p),
true,
global_mode_snapshot_buffer,
sizeof (global_mode_snapshot_buffer));