Documenting the API
This document contains general guidelines for describing the Tarantool API, as well as examples and templates.
Please write as simply as possible. Describe functionality using short sentences in the present simple tense. A short sentence consists of no more than two clauses. Consider using LanguageTool or Grammarly to check your English. For more style-related specifics, consult the Language and style section.
For every new module, function, or method, specify the version it first appears in.
For a new parameter, specify the version it first appears in if this parameter is a «feature» and the version it’s been introduced in differs from the version introducing the function/method and all other parameters.
To specify the version, use the following Sphinx directive:
Since :doc:`2.10.0 </release/2.10.0>`.
This is a link to the release notes on the Tarantool documentation website.
The result looks like this:
Since Tarantool 2.10.0. This is a link to the release notes on the Tarantool documentation website.
Use one of the two options:
- Start with a verb in the imperative mood. Example: Create a fiber.
- Start with a noun. Example: The directory where memtx stores snapshot files.
Each list item is a characteristic to be described. Some items can be optional.
- 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)
- 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 additionally 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 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)
In the «Possible errors» section of a function or class method, consider explaining what happens if any parameter hasn’t been defined or has the wrong value.
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.
Параметры: - 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: :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
) – 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 (
-
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 ...
-
Example:
.. _cfg_basic-vinyl_dir:
.. confval:: vinyl_dir
Since version 1.7.1.
A directory where vinyl files or subdirectories will be stored. Can be
relative to :ref:`work_dir <cfg_basic-work_dir>`. If not specified, defaults
to ``work_dir``.
|
| Type: string
Result: