fix or add missed document.

- fix typo. - replace bool to void from jerry_api_set_object_native_handle - remove invalid build precondition - remove argument from jerry_api_create_object description - add jerry_api_create_array_object description - add jerry_api_set_array_index_value description - add jerry_api_get_array_index_value description - add jerry_api_release_value description - add jerry_api_create_error description JerryScript-DCO-1.0-Signed-off-by: pius.lee pius.lee@samsung.com
2015-10-06 20:51:44 +09:00
parent 3206a16923
commit dd20004d37
2 changed files with 232 additions and 8 deletions
@@ -35,7 +35,7 @@ These tools are required for development:

 {% highlight bash %}
 sudo apt-get install gcc g++
-sudo apt-get install gcc-arm-none-eabi g++-arm-none-eabi
+sudo apt-get install gcc-arm-none-eabi
 sudo apt-get install cmake
 sudo apt-get install libpcre3 libpcre3-dev
 sudo apt-get install tcl8.6 tcl8.6-dev tk8.6-dev libboost-all-dev
@@ -310,7 +310,7 @@ jerry_api_string_to_char_buffer (const jerry_api_string_t * string_p,
 - `buffer_size` - size of the buffer;
 - returned value:
  - number of bytes, actually copied to the buffer - if characters were copied successfully;
-  - otherwise (in case size of buffer is insuficcient) - negative number, which is calculated as negation of buffer size, that is required to hold characters.
+  - otherwise (in case size of buffer is insufficient) - negative number, which is calculated as negation of buffer size, that is required to hold characters.

 **Example**

@@ -441,17 +441,16 @@ Upon the JavaScript object becomes unused, all pointers to it should be released

 {% highlight cpp %}
 jerry_api_object_t*
-jerry_api_create_object (const char * v);
+jerry_api_create_object ();
 {% endhighlight %}

- `v` - value of object to create;
 - returned value is pointer to the created object.

 **Example**

 {% highlight cpp %}
 {
-  jerry_api_object_t * object_p = jerry_api_create_object ("abc");
+  jerry_api_object_t * object_p = jerry_api_create_object ();

  ...

@@ -491,7 +490,7 @@ jerry_api_acquire_object (jerry_api_object_t * object_p);

 {% highlight cpp %}
 {
-  jerry_api_object_t * obj_ptr1_p = jerry_api_create_object ("abc");
+  jerry_api_object_t * obj_ptr1_p = jerry_api_create_object ();
  jerry_api_object_t * obj_ptr2_p = jerry_api_acquire_object (obj_ptr1_p);

  ... // usage of both pointers
@@ -527,7 +526,7 @@ jerry_api_release_object (jerry_api_object_t * object_p);

 {% highlight cpp %}
 {
-  jerry_api_object_t * obj_ptr1_p = jerry_api_create_object ("abc");
+  jerry_api_object_t * obj_ptr1_p = jerry_api_create_object ();
  jerry_api_object_t * obj_ptr2_p = jerry_api_acquire_object (obj_ptr1_p);

  ... // usage of both pointers
@@ -802,7 +801,7 @@ If native handle or "free" callback were already set for the object, correspondi
 **Prototype**

 {% highlight cpp %}
-bool
+void
 jerry_api_set_object_native_handle (jerry_api_object_t * object_p,
                                    uintptr_t handle,
                                    jerry_object_free_callback_t freecb_p);
@@ -1099,3 +1098,228 @@ handler (const jerry_api_object_t * function_obj_p,
 - [jerry_api_is_function](#jerryapiisfunction)
 - [jerry_api_call_function](#jerryapicallfunction)
 - [jerry_api_release_object](#jerryapireleaseobject)
+
+# jerry_api_create_array_object
+
+**Summary**
+Create new JavaScript array object.
+
+Upon the JavaScript array object becomes unused, all pointers to it should be released using [jerry_api_release_object](#jerryapireleaseobject).
+
+**Prototype**
+
+{% highlight cpp %}
+jerry_api_object_t*
+jerry_api_create_array_object (jerry_api_size_t array_size);
+{% endhighlight %}
+
+ - `array_size` - size of array;
+ - returned value is pointer to the created array object.
+
+ **Example**
+
+{% highlight cpp %}
+{
+    jerry_api_object_t * array_object_p = jerry_api_create_array_object (10);
+
+    ...
+
+    jerry_api_release_object (array_object_p);
+}
+{% endhighlight %}
+
+**See also**
+
+- [jerry_api_acquire_object](#jerryapiacquireobject)
+- [jerry_api_release_object](#jerryapireleaseobject)
+- [jerry_api_set_array_index_value](#jerryapisetarrayindexvalue)
+- [jerry_api_get_array_index_value](#jerryapigetarrayindexvalue)
+- [jerry_api_add_object_field](#jerryapiaddobjectfield)
+- [jerry_api_delete_object_field](#jerryapideleteobjectfield)
+- [jerry_api_get_object_field_value](#jerryapigetobjectfieldvalue)
+- [jerry_api_set_object_field_value](#jerryapisetobjectfieldvalue)
+- [jerry_api_get_object_native_handle](#jerryapigetobjectnativehandle)
+- [jerry_api_set_object_native_handle](#jerryapisetobjectnativehandle)
+
+# jerry_api_set_array_index_value
+
+**Summary**
+Set value of an indexed element in the specified array object.
+
+**Prototype**
+
+{% highlight cpp %}
+bool
+jerry_api_set_array_index_value (jerry_api_object_t * array_object_p,
+                                 jerry_api_length_t index,
+                                 jerry_api_value_t * value_p);
+{% endhighlight %}
+
+- `array_object_p` - pointer to the array object;
+- `index` - index of the array element;
+- `value_p` - indexed value to set;
+- returned value - true, if value was set successfully.
+
+**Example**
+
+{% highlight cpp %}
+{
+    jerry_api_object_t * array_object_p = jerry_api_create_array_object (10);
+    jerry_api_value_t val;
+
+    ... // receive or construct val
+
+    jerry_api_set_array_index_value (array_object_p, 5, &val);
+
+    jerry_api_release_object (array_object_p);
+}
+{% endhighlight %}
+
+**See also**
+
+- [jerry_api_value_t](#jerryapivaluet)
+- [jerry_api_create_array_object](#jerryapicreatearrayobject)
+
+# jerry_api_get_array_index_value
+
+**Summary**
+Get value of an indexed element in the specified array object.
+
+**Prototype**
+
+{% highlight cpp %}
+bool
+jerry_api_get_array_index_value (jerry_api_object_t * array_object_p,
+                                 jerry_api_length_t index,
+                                 jerry_api_value_t * value_p);
+{% endhighlight %}
+
+- `array_object_p` - pointer to the array object;
+- `index` - index of the array element;
+- `value_p` - retrieved indexed value (output parameter);
+- returned value - true, if value was retrieved successfully.
+
+**Example**
+
+{% highlight cpp %}
+{
+    jerry_api_object_t* array_object_p;
+    ... // receive or construct array_object_p
+
+    jerry_api_value_t val;
+    bool is_ok = jerry_api_get_array_index_value (array_object_p, 5, &val);
+    if (is_ok)
+    {
+        ... // usage of 'val'
+    }
+}
+{% endhighlight %}
+
+**See also**
+
+- [jerry_api_value_t](#jerryapivaluet)
+- [jerry_api_create_array_object](#jerryapicreatearrayobject)
+
+# jerry_api_release_value
+
+**Summary**
+Release specified pointer to the value.
+
+**Prototype**
+
+{% highlight cpp %}
+void
+jerry_api_release_value (jerry_api_value_t * value_p);
+{% endhighlight %}
+
+- `value_p` - pointer to the value.
+
+**Example**
+{% highlight cpp %}
+{
+    jerry_api_value_t val1;
+    jerry_api_value_t val2;
+
+    val1.type = JERRY_API_DATA_TYPE_OBJECT;
+    val1.v_object = jerry_api_create_object ();
+
+    val2.type = JERRY_API_DATA_TYPE_STRING;
+    val2.v_string = jerry_api_create_string ("abc");
+
+    ... // usage of val1
+
+    jerry_api_release_value (&val1);
+
+    ... // usage of val2
+
+    jerry_api_release_value (&val2);
+}
+{% endhighlight %}
+
+**See also**
+
+- [jerry_api_value_t](#jerryapivaluet)
+
+# jerry_api_create_error
+
+**Summary**
+Create new JavaScript error object.
+it should be throwed inside of handle attached to external function object.
+
+**Prototype**
+
+{% highlight cpp %}
+jerry_api_object_t*
+jerry_api_create_error (jerry_api_error_t error_type,
+                        const jerry_api_char_t * message_p);
+{% endhighlight %}
+
+- `error_type` - error type of object;
+- `message_p` - human-readable description of the error;
+- returned value is pointer to the created error object.
+
+**Example**
+
+{% highlight cpp %}
+static bool
+handler (const jerry_api_object_t * function_obj_p,
+         const jerry_api_value_t * this_p,
+         jerry_api_value_t * ret_val_p,
+         const jerry_api_value_t args_p[],
+         const uint16_t args_cnt)
+{
+  jerry_api_object_t * error_p = jerry_api_create_error (JERRY_API_ERROR_TYPE,
+                                                         (jerry_api_char_t *) "error");
+
+  jerry_api_acquire_object (error_p);
+  ret_val_p->type = JERRY_API_DATA_TYPE_OBJECT;
+  ret_val_p->v_object = error_p;
+
+  jerry_api_release_object (error_p);
+
+  return false;
+}
+
+{
+  jerry_api_object_t * throw_obj_p = jerry_api_create_external_function (handler);
+  jerry_api_object_t * glob_obj_p = jerry_api_get_global ();
+
+  jerry_api_value_t val;
+  val.type = JERRY_API_DATA_TYPE_OBJECT;
+  val.v_object = throw_obj_p;
+
+  // after this, script can invoke the native handler through "error_func ();"
+  // and "error_func" throw a error on called
+  jerry_api_set_object_field_value (glob_obj_p, "error_func", &val);
+
+  jerry_api_release_object (glob_obj_p);
+  jerry_api_release_object (throw_obj_p);
+}
+{% endhighlight %}
+
+**See also**
+- [jerry_external_handler_t](#jerryexternalhandlert)
+- [jerry_api_is_function](#jerryapiisfunction)
+- [jerry_api_call_function](#jerryapicallfunction)
+- [jerry_api_release_object](#jerryapireleaseobject)
+- [jerry_api_create_external_function](#jerryapicreateexternalfunction)