Рейтинг@Mail.ru

4.2. Documentation guidelines

4.2. Documentation guidelines

These guidelines are updated on the on-demand basis, covering only those issues that cause pains to the existing writers. At this point, we do not aim to come up with an exhaustive Documentation Style Guide for the Tarantool project.

4.2.1. Markup issues

4.2.1.1. Wrapping text

The limit is 80 characters per line for plain text, and no limit for any other constructions when wrapping affects ReST readability and/or HTML output. Also, it makes no sense to wrap text into lines shorter than 80 characters unless you have a good reason to do so.

The 80-character limit comes from the ISO/ANSI 80x24 screen resolution, and it’s unlikely that readers/writers will use 80-character consoles. Yet it’s still a standard for many coding guidelines (including Tarantool). As for writers, the benefit is that an 80-character page guide allows keeping the text window rather narrow most of the time, leaving more space for other applications in a wide-screen environment.

4.2.1.2. Formatting code snippets

For code snippets, we mainly use the code-block directive with an appropriate highlighting language. The most commonly used highlighting languages are:

  • .. code-block:: tarantoolsession
  • .. code-block:: console
  • .. code-block:: lua

For example (a code snippet in Lua):

for page in paged_iter("X", 10) do
  print("New Page. Number Of Tuples = " .. #page)
  for i=1,#page,1 do print(page[i]) end
end

In rare cases, when we need custom highlight for specific parts of a code snippet and the code-block directive is not enough, we use the per-line codenormal directive together and explicit output formatting (defined in doc/sphinx/_static/sphinx_design.css).

Examples:

  • Function syntax (the placeholder space-name is displayed in italics):

    box.space.space-name:create_index(‘index-name’)

  • A tdb session (user input is in bold, command prompt is in blue, computer output is in green):

    $ tarantool example.lua
    (TDB)  Tarantool debugger v.0.0.3. Type h for help
    example.lua
    (TDB)  [example.lua]
    (TDB)  3: i = 1
    

Warning: Every entry of explicit output formatting (codenormal, codebold, etc) tends to cause troubles when this documentation is translated to other languages. Please avoid using explicit output formatting unless it is REALLY needed.

4.2.1.5. Making comments

Sometimes we may need to leave comments in a ReST file. To make sphinx ignore some text during processing, use the following per-line notation with ”.. //” as the comment marker:

.. // your comment here

The starting symbols ”.. //” do not interfere with the other ReST markup, and they are easy to find both visually and using grep. There are no symbols to escape in grep search, just go ahead with something like this:

grep ".. //" doc/sphinx/dev_guide/*.rst

These comments don’t work properly in nested documentation, though (e.g. if you leave a comment in module -> object -> method, sphinx ignores the comment and all nested content that follows in the method description).

4.2.2. Language and style issues

4.2.2.1. US vs British spelling

We use English US spelling.

4.2.3. Examples and templates

4.2.3.1. Module and function

Here is an example of documenting a module (my_fiber) and a function (my_fiber.create).

my_fiber.create(function[, function-arguments])

Create and start a my_fiber object. The object is created and begins to run immediately.

Parameters:
  • function – the function to be associated with the my_fiber object
  • function-arguments – what will be passed to function
Return:

created my_fiber object

Rtype:

userdata

Example:

tarantool> my_fiber = require('my_fiber')
---
...
tarantool> function function_name()
         >   my_fiber.sleep(1000)
         > end
---
...
tarantool> my_fiber_object = my_fiber.create(function_name)
---
...

4.2.3.2. Module, class and method

Here is an example of documenting a module (my_box.index), a class (my_index_object) and a function (my_index_object.rename).

object my_index_object
my_index_object:rename(index-name)

Rename an index.

Parameters:
  • index_object – an object reference
  • index_name – a new name for the index (type = string)
Return:

nil

Possible errors: index_object does not exist.

Example:

tarantool> box.space.space55.index.primary:rename('secondary')
---
...

Complexity Factors: Index size, Index type, Number of tuples accessed.