JerryScript Documentation

When writing code for JerryScript, use a verbose function declaration format to reduce maintenance costs and improve readability.

Key requirements for a compliant function declaration:

1. Doxygen-style header: Include a short overview, a detailed explanation (if necessary), and an @return description.
2. Argument documentation: Use /**< description */ inline for each argument.
3. Return type placement: Place the return type on a separate line above the function name.
4. Closing comment: Include a comment at the end of the function body containing the function name (e.g., } /* function_name */).

/**
 * Short overview about the purpose of this function.
 *
 * A more detailed explanation if needed.
 *
 * Note:
 *   Extra notes if needed.
 *
 * @return short description about the value
 *         returned by the function
 */
return_value_type_t
function_name (argument1, /**< description of argument1 */
               argument2, /**< description of argument2 */
               ...
               argument_n, /**< description of argument n */
{

  /* Function body. */

} /* function_name */

When performing property operations like jerry_object_get or jerry_object_set, you must manage the references for both the retrieved/set value and the result of the operation itself.

• jerry_object_get: Returns a new live reference to the property value. If the operation fails, it returns a live reference to an error object. Both must be freed.
• jerry_object_set:
  1. The value being set (new_prop_value) must be released.
  2. The result of the operation (result) is a new live reference (representing a primitive or an error) and must also be released.

  jerry_value_t new_prop_value = jerry_number (2.718);
  jerry_value_t result = jerry_object_set (..., new_prop_value);

  /* The new_prop_value can be passed to other JerryScript API
   * functions before the jerry_value_free () call. */
  jerry_value_free (new_prop_value);

  /* The reference stored in the 'result' variable is live whether
   * the operation is successful or not, and must also be freed. */
  if (jerry_value_is_exception (result))
  {
    /* Errors can be handled here. */
  }
  jerry_value_free (result);

To use the JerryScript library, you must clone and build it for your target environment. The following steps demonstrate building with the default configuration and installing it to a local directory on a Linux system.

After installation, the library headers and libraries will be located in the example_install/{include,lib} directories. To use pkg-config to manage includes and libraries, you must export the PKG_CONFIG_PATH pointing to the installation's lib/pkgconfig directory.

$ mkdir jerry
$ cd jerry
$ git clone https://github.com/jerryscript-project/jerryscript.git
$ jerryscript/tools/build.py --builddir=$(pwd)/example_build --cmake-param="-DCMAKE_INSTALL_PREFIX=$(pwd)/example_install/"
$ make -C $(pwd)/example_build install

# Set up pkg-config
$ export PKG_CONFIG_PATH=$(pwd)/example_install/lib/pkgconfig/

# Verify pkg-config works
$ pkg-config --cflags --libs libjerry-core libjerry-port libjerry-ext libjerry-math