Версия:

Руководство разработчика / Рекомендации / Рекомендации по написанию документации
Руководство разработчика / Рекомендации / Рекомендации по написанию документации

Рекомендации по написанию документации

Рекомендации по написанию документации

Данные рекомендации обновляются по запросу, охватывая только те проблемы, которые вызывают вопросы у авторов документации. На данный момент мы не стремимся разработать исчерпывающее руководство по написанию документации для проекта Tarantool.

Вопросы по разметке

Перенос текста

Строка ограничена 80 символами для обычного текста и никак не ограничена для любых других конструкций, когда обтекание влияет на читаемость ReST и / или HTML-вывод. Кроме того, нет смысла переносить текст в строках короче 80 символов, если у вас для этого нет веских оснований.

Ограничение в 80 символов исходит из разрешения экрана ISO/ANSI 80x24, и маловероятно, что читатели/писатели будут использовать 80-символьные консоли. Тем не менее, такое ограничение по-прежнему является стандартом во многих рекомендациях по программированию (включая Tarantool). Что касается писателей, то благодаря ограничению размера страницы окно с текстом может быть довольно узким, оставляя больше места для других приложений в широкоэкранном окружении.

Форматирование фрагментов кода

Для фрагментов коды мы обычно используем директиву code-block с соответствующей подсветкой синтаксиса языка. Чаще всего используем следующее:

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

Например (фрагмент 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

В редких случаях при необходимости подсветить отдельные части фрагмента кода, когда директивы code-block недостаточно, мы используем директиву codenormal построчно вместе с явным форматированием вывода (как указано в doc/sphinx/_static/sphinx_design.css).

Примеры:

  • Синтаксис функции (объект-заполнитель имя-спейса отображается курсивом):

    box.space.имя-спейса:create_index(„index-name“)

  • Сессия tdb (ввод информации пользователем выделяется жирным шрифтом, приглашение на ввод команды – синим, вывод – зеленым):

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

Внимание: Каждая запись с явным форматированием вывода (codenormal, codebold и т.п.) часто вызывает трудности при переводе документации на другие языки. Постарайтесь избегать специального форматирования, если только без него никак НЕЛЬЗЯ обойтись.

Добавление комментариев

Иногда могут потребоваться комментарии в файле ReST. Чтобы sphinx не учитывал этот текст во время обработки, используйте следующую запись в каждой строке в качестве маркера комментария («.. //»):

.. // здесь комментарий

Начальные символы «.. //» не пересекаются с другими символами разметки ReST, и их легко обнаружить как визуально, так и с помощью grep. В поиске grep нет символов, которые нужно избегать, просто выполните примерно следующее:

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

Тем не менее, эти комментарии не сработают должным образом во вложенной документации (например, если оставить комментарий в модуле -> объекте -> методе, sphinx игнорирует комментарий и всё вложенное содержимое, который следует в описании метода).

Вопросы по стилю и языку

Британский или американский вариант английского

В английской версии документации мы придерживаемся американского варианта английского языка.

Экземпляр или сервер

Ссылаясь на экземпляр Tarantool-сервера, мы говорим «экземпляр», а не «сервер». Это обеспечивает однородность терминологии в руководстве и именами в окружении Tarantool’а (например, /etc/tarantool/instances.enabled – активные экземпляры).

Неправильно: «С помощью репликации несколько серверов Tarantool’а могут работать на копиях одинаковых баз данных.»

Правильно: «С помощью репликации несколько экземпляров Tarantool’а могут работать на копиях одинаковых баз данных.»

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

Модуль и функция

Ниже приводится пример документирования модуля (my_fiber) и функции (my_fiber.create).

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

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

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

созданный объект my_fiber

тип возвращаемого значения:
 

пользовательские данные

Пример:

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

Модуль, класс и метод

Ниже приводится пример документирования модуля (my_box.index), класса (my_index_object) и функции (my_index_object.rename).

object my_index_object
my_index_object:rename(index-name)

Переименование индекса.

Параметры:
  • index_object – ссылка на объект
  • index_name – новое имя для индекса (тип = строка)
возвращается:

nil

Возможные ошибки: index_object не существует.

Пример:

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

Факторы сложности: Размер индекса, тип индекса, количество кортежей, к которым получен доступ.