Documenting the API

Function or method

• Since which Tarantool version
• General description
• Parameters
• What this function returns (if nothing, write ‘none’)
• Return type (if exists)
• Possible errors (if exist)
• Complexity factors (for CRUD operations and index access functions)
• Usage with memtx and vinyl (if differs)
• Example(s)
• Extra information (if needed)

See module function example, class method example.

Data

• Since which Tarantool version
• General description
• Return type
• Example

See class data example.

Function and method parameters

• Since which Tarantool version (if added later)
• General description
• Type
• Default value (if optional), possible values

If the parameter is optional, make sure it is enclosed in square brackets in the function declaration (in the “heading”). Do not mark parameters additionaly as “optional” or “required”:

..  function:: format(URI-components-table[, include-password])

    Construct a URI from components.

    :param URI-components-table: a series of ``name:value`` pairs, one for each component
    :param include-password: boolean. If this is supplied and is ``true``, then
                             the password component is rendered in clear text,
                             otherwise it is omitted.

Configuration parameters

Configuration parameters are not to be confused with class and method parameters. Configuration parameters are passed to Tarantool via the command line or in an initialization file. You can find a list of Tarantool configuration parameters in the configuration reference.

• Since which Tarantool version
• General description
• Type
• Corresponding environment variable (if applicable)
• Default value
• Possible values (can be included in the general description, for example, as a list)
• Dynamic (yes or no)

See configuration parameter example.

Module functions

We use the Sphinx directives .. module:: and .. function:: to describe functions of Tarantool modules:

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

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

Class methods and data

Methods are described similarly to functions, but the .. class:: directive, unlike .. module::, requires nesting.

As for data, it’s enough to write the description, the return type, and an example.

Here is the example documentation describing the method and data of the index_object class:

..  class:: index_object

    ..  method:: get(key)

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

        :param index_object index_object: :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:	index_object (index_object) – object reference key (scalar/table) – 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 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
...

Configuration parameters

Example:

    In that situation, queries may time out after ``vinyl_timeout`` seconds.
    This should rarely occur, since normally vinyl
    would throttle inserts when it is running low on compaction bandwidth.
    Compaction can also be ordered manually with
    :doc:`/reference/reference_lua/box_index/compact`.

    |
    | Type: float
    | Default: 60
    | Environment variable: TT_VINYL_TIMEOUT
    | Dynamic: yes

.. _cfg_basic-username:

Result:

This should rarely occur, since normally vinyl would throttle inserts when it is running low on compaction bandwidth. Compaction can also be ordered manually with index_object:compact().

Type: float

Default: 60

Environment variable: TT_VINYL_TIMEOUT

Dynamic: yes