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: - index_object (index_object) – an 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'] ...
-