Examples and templates
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
- Parameters
- 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)
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 --- ...
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.
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'] ...
-