Top.Mail.Ru
Examples and templates | Tarantool
 
Contributing / Guidelines / Documentation guidelines / Examples and templates
Contributing / Guidelines / Documentation guidelines / Examples and templates

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
...