Top.Mail.Ru
Examples and templates | Tarantool
 

Examples and templates

Examples and templates

In this document, we explain general guidelines for describing Tarantool API and give some examples and templates.

Use this checklist for documenting a function or a method:

  • Base description
  • Parameters
  • What this function returns (if nothing, write ‘none’)
  • Return type (if exists)
  • Possible errors (if exist)
  • Complexity factors (if exist)
  • Note re storage engine (if exists)
  • Example(s)
  • Extra information (if needed)

We describe functions of Tarantool modules via Sphinx directives .. module:: and .. function:::

..  module:: fiber

..  function:: create(function [, function-arguments])

    Create and start a fiber. The fiber is created and begins to run immediately.

    :param function: the function to be associated with the fiber
    :param function-arguments: what will be passed to function

    :return: created fiber object
    :rtype: userdata

    **Example:**

    ..  code-block:: tarantoolsession

        tarantool> fiber = require('fiber')
        ---
        ...
        tarantool> function function_name()
                 >   print("I'm a fiber")
                 > end
        ---
        ...
        tarantool> fiber_object = fiber.create(function_name); print("Fiber started")
        I'm a fiber
        Fiber started
        ---
        ...

And the resulting output looks like this:

fiber.create(function[, function-arguments])

Create and start a fiber. The fiber is created and begins to run immediately.

Parameters:
  • function – the function to be associated with the fiber
  • function-arguments – what will be passed to function
Return:

created fiber object

Rtype:

userdata

Example:

tarantool> fiber = require('fiber')
---
...
tarantool> function function_name()
         >   print("I'm a fiber")
         > end
---
...
tarantool> fiber_object = fiber.create(function_name); print("Fiber started")
I'm a fiber
Fiber started
---
...

Description of a method is similar to a function, but the .. class:: directive, unlike .. module::, requires nesting.

As for documenting data, it will be enough to write a description, a return type, and an example.

Here is an example of documenting a method and data of a class index_object:

..  class:: index_object

    ..  method:: get(key)

        Search for a tuple :ref:`via the given index <box_index-note>`.

        :param index_object index_object: an :ref:`object reference
                                          <app_server-object_reference>`.
        :param scalar/table      key: values to be matched against the index key

        :return: the tuple whose index-key fields are equal to the passed key values
        :rtype:  tuple

        **Possible errors:**

        * no such index;
        * wrong type;
        * more than one tuple matches.

        **Complexity factors:** Index size, Index type.
        See also :ref:`space_object:get() <box_space-get>`.

        **Example:**

        ..  code-block:: tarantoolsession

            tarantool> box.space.tester.index.primary:get(2)
            ---
            - [2, 'Music']
            ...

    ..  data:: unique

        True if the index is unique, false if the index is not unique.

        :rtype: boolean

        ..  code-block:: tarantoolsession

            tarantool> box.space.tester.index.primary.unique
            ---
            - true
            ...

And the resulting output looks like this:

object index_object
index_object:get(key)

Search for a tuple via the given index.

Parameters:
Return:

the tuple whose index-key fields are equal to the passed key values

Rtype:

tuple

Possible errors:

  • no such index;
  • wrong type;
  • more than one tuple matches.

Complexity factors: Index size, Index type. See also space_object:get().

Example:

tarantool> box.space.tester.index.primary:get(2)
---
- [2, 'Music']
...
index_object.unique

True if the index is unique, false if the index is not unique.

Rtype:boolean
tarantool> box.space.tester.index.primary.unique
---
- true
...