Примеры и шаблоны

This document contains general guidelines for describing the Tarantool API, as well as examples and templates.

Use this checklist for documenting a function or a method:

Base description
Параметры
What this function returns (if nothing, write „none“)
Return type (if exists)
Possible errors (if exist)
Complexity factors (if exist)
Usage with memtx and vinyl (if differs)
Example(s)
Extra information (if needed)

Documenting 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])¶

Создание и запуск файбера. Происходит создание файбера, который незамедлительно начинает работу.

возвращаемое значение:
Параметры:	function – функция, которая будет связана с файбером function-arguments – что передается в функцию
возвращает:	созданный объект файбера
	пользовательские данные

Пример:

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

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

возвращаемое значение:
Параметры:	index_object (`index_object`) – ссылка на объект. key (`scalar/table`) – значения для сопоставления с ключом индекса
возвращает:	the tuple whose index-key fields are equal to the passed key values
	кортеж

Возможные ошибки:

отсутствие такого индекса;
неправильный тип;
больше одного кортежа подходят.

Факторы сложности: Размер индекса, тип индекса. См. также space_object:get().

Пример:

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

index_object.unique¶

Если индекс уникальный – true, если индекс не уникален – false.

возвращаемое значение:
	boolean (логический)

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

Версия:

Примеры и шаблоны

Documenting functions

Documenting class methods and data