Документация

Julia позволяет разработчикам и пользователям пакетов легко документировать функции, типы и другие объекты с помощью встроенной системы документирования начиная с версии Julia 0.4.

Базовый синтаксис очень прост: любая строка, появляющаяся на верхнем уровне непосредственно перед объектом (функцией, макросом, типом или экземпляром), будет интерпретироваться как его документация (они называются строками документации). Вот очень простой пример:

"Tell whether there are too foo items in the array."
foo(xs::Array) = ...

Документация интерпретируется как Markdown, поэтому вы можете использовать отступы и блоки кода для разграничения примеров кода от текста. Технически, любой объект может быть связан с любым другим как метаданные; Markdown является по умолчанию, но можно создать другие макросы строк и передать их в макрос @doc также.

Вот более сложный пример, также использующий Markdown:

"""
    bar(x[, y])

Compute the Bar index between `x` and `y`. If `y` is missing, compute
the Bar index between all pairs of columns of `x`.

# Examples
```julia
julia> bar([1, 2], [1, 2])
1
```
"""
function bar(x, y) ...

Как и в примере выше, мы рекомендуем следовать некоторым простым соглашениям при написании документации:

1. Всегда отображайте сигнатуру функции в верхней части документации с отступом в четыре пробела, чтобы она печаталась как код Julia.

   Это может быть идентично сигнатуре, присутствующей в коде Julia (например, mean(x::AbstractArray)), или упрощённой форме. Должны быть представлены необязательные аргументы с их значениями по умолчанию (т.е. f(x, y=1)), когда это возможно, следуя фактическому синтаксису Julia. Необязательные аргументы, не имеющие значения по умолчанию, должны быть помещены в скобки (т.е. f(x[, y]) и f(x[, y[, z]])). Альтернативным решением является использование нескольких строк: одна без необязательных аргументов, а другие — с ними. Это решение также может использоваться для документирования нескольких взаимосвязанных методов данной функции. Когда функция принимает множество ключевых аргументов, включите только заполнитель <keyword arguments> в сигнатуре (т.е. f(x; <keyword arguments>)), и предоставьте полный список в разделе # Arguments (см. пункт 4 ниже).

2. Включите однострочное предложение, описывающее, что делает функция или что представляет собой объект, после блока упрощенной сигнатуры. При необходимости предоставьте более подробные сведения во втором абзаце, после пустой строки.

   Однострочное предложение должно использовать повелительное наклонение («Сделайте это», «Возвращает это») вместо третьего лица (не пишите «Возвращает длину…») при документировании функций. Оно должно заканчиваться точкой. Если смысл функции нельзя легко обобщить, разбитие на отдельные составные части может быть полезным (хотя это не следует рассматривать как абсолютное требование для каждого отдельного случая).

3. Не повторяйтесь.

   Поскольку имя функции задаётся сигнатурой, нет необходимости начинать документацию со слов «Функция bar…»: переходите сразу к сути. Аналогично, если сигнатура указывает типы аргументов, упоминание их в описании избыточно.

4. Предоставляйте список аргументов только тогда, когда это действительно необходимо.

   Для простых функций часто понятнее указать роль аргументов непосредственно в описании назначения функции. Список аргументов будет просто повторять информацию, уже предоставленную где-то ещё. Однако, предоставление списка аргументов может быть хорошей идеей для сложных функций с множеством аргументов (особенно ключевых аргументов). В этом случае вставьте его после общего описания функции, под заголовком # Arguments, с одной пулей * для каждого аргумента. В списке должны быть указаны типы и значения по умолчанию (если таковые имеются) аргументов:

   """
   ...
   # Arguments
   * `n::Integer`: the number of elements to compute.
   * `dim::Integer=1`: the dimensions along which to perform the computation.
   ...
   """
   

5. Включите любые примеры кода в разделе # Examples.

   Примеры, когда это возможно, должны быть написаны как doctest. Doctest — это блок кода в рамке (см. Блоки кода), начинающийся с ```jldoctest и содержащий любое количество julia> запросов вместе с входными данными и ожидаемыми результатами, имитирующими Julia REPL.

   Например, в следующем строке документации определяется переменная a, и после этого появляется ожидаемый результат, как он отображается в Julia REPL:

   """
   Some nice documentation here.
   
   # Examples
   
   ```jldoctest
   julia> a = [1 2; 3 4]
   2×2 Array{Int64,2}:
    1  2
    3  4
   ```
   """
   

   Предупреждение

   Вызов rand и других функций, связанных с генерацией случайных чисел, следует избегать в doctest, так как они не будут давать согласованных результатов в различных сеансах Julia.

   Размерность слов операционной системы (Int32 или Int64) а также различия в разделителях путей (/ или \) также повлияют на воспроизводимость некоторых doctest.

   Обратите внимание, что пробелы в вашем doctest важны! Doctest завершится неудачей, если вы неправильно выровняете вывод при красивой печати массива, например.

   Затем вы можете запустить make -C doc doctest для выполнения всех doctest в руководстве Julia, что обеспечит работоспособность вашего примера.

   Примеры, которые не могут быть протестированы, должны быть написаны в блоках кода в рамке, начинающихся с ```julia, чтобы они правильно выделялись в сгенерированной документации.

   Подсказка

   По возможности примеры должны быть самодостаточными и выполняемыми, чтобы читатели могли их опробовать без необходимости включения каких-либо зависимостей.

6. Используйте обратные кавычки для идентификации кода и уравнений.

   Идентификаторы Julia и фрагменты кода должны всегда отображаться между обратными кавычками ` для выделения. Уравнения в синтаксисе LaTeX могут быть вставлены между двойными обратными кавычками ``. Используйте символы Юникода вместо их последовательностей с эскейпом LaTeX, т.е. ``α = 1`` вместо ``\\alpha = 1``.

7. Помещайте начальные и конечные """ символы на отдельных строках.

   То есть, запишите:

   """
   ...
   
   ...
   """
   f(x, y) = ...
   

   а не:

   """...
   
   ..."""
   f(x, y) = ...
   

   Это делает более понятным, где начинаются и заканчиваются строки документации.

8. Учитывайте ограничение длины строки, используемое в окружающем коде.

   Строки документации редактируются с помощью тех же инструментов, что и код. Поэтому должны применяться те же соглашения. Рекомендуется добавлять переводы строк после 92 символов.

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

Документация может быть доступна в REPL или IJulia, набрав ? за которым следует имя функции или макроса, и нажав Enter. Например,

?fft
?@time
?r""

покажет документацию для соответствующей функции, макроса или макроса строк соответственно. В Juno использование Ctrl-J, Ctrl-D покажет документацию для объекта под курсором.

Функции и методы

Функции в Julia могут иметь несколько реализаций, известных как методы. Хотя для общих функций рекомендуется иметь единственное назначение, Julia позволяет документировать методы индивидуально при необходимости. В общем случае должна быть задокументирована только наиболее общая функция, или даже сама функция (т.е. объект, созданный без методов function bar end). Конкретные методы должны быть задокументированы только в том случае, если их поведение отличается от более общих. В любом случае они не должны повторять информацию, предоставленную где-либо ещё. Например:

"""
Multiplication operator. `x*y*z*...` calls this function with multiple
arguments, i.e. `*(x,y,z...)`.
"""
function *(x, y)
  # ... [implementation sold separately] ...
end

"When applied to strings, concatenates them."
function *(x::AbstractString, y::AbstractString)
  # ... [insert secret sauce here] ...
end

help?>*
Multiplication operator. `x*y*z*...` calls this function with multiple
arguments, i.e. `*(x,y,z...)`.

When applied to strings, concatenates them.

При получении документации для общей функции метаданные для каждого метода конкатенируются с функцией catdoc, которая, конечно, может быть переопределена для пользовательских типов.

Расширенное использование

Макрос @doc связывает свой первый аргумент со своим вторым в словаре по модулям, называемом META. По умолчанию ожидается, что документация написана на Markdown, и макрос строк doc"" просто создаёт объект, представляющий содержимое Markdown. В будущем он, вероятно, будет выполнять более сложные задачи, такие как разрешение относительных путей к изображениям или ссылкам.

При использовании для получения документации макрос @doc (или, аналогично, функция doc ) будет искать во всех словарях META метаданные, относящиеся к заданному объекту, и возвращать их. Возвращаемый объект (например, некоторое содержимое Markdown) по умолчанию будет разумно отображаться сам по себе. Этот дизайн также делает лёгким программно использовать систему документирования, например, для повторного использования документации между различными версиями функции:

@doc "..." foo!
@doc (@doc foo!) foo

Или для использования с метапрограммированием Julia:

for (f, op) in ((:add, :+), (:subtract, :-), (:multiply, :*), (:divide, :/))
    @eval begin
        $f(a,b) = $op(a,b)
    end
end
@doc "`add(a,b)` adds `a` and `b` together" add
@doc "`subtract(a,b)` subtracts `b` from `a`" subtract

Документация, написанная в блоках, не являющихся блоками верхнего уровня, таких как if, for, и let, не добавляется автоматически в систему документирования. @doc необходимо использовать в этих случаях. Например:

if VERSION > v"0.4"
    "..."
    f(x) = x
end

не добавит никакой документации к f даже когда условие является true и вместо этого должна быть написана как:

if VERSION > v"0.4"
    @doc "..." ->
    f(x) = x
end

Руководство по синтаксису

Полноценный обзор всего документируемого синтаксиса Julia.

В следующих примерах "..." используется для иллюстрации произвольной строки документации, которая может быть одной из следующих четырёх вариантов и содержать произвольный текст:

"..."

doc"..."

"""
...
"""

doc"""
...
"""

@doc_str следует использовать только тогда, когда строка документации содержит $ или \ символы, которые не должны быть проанализированы Julia, такие как синтаксис LaTeX или примеры кода Julia, содержащие интерполяцию.

Функции и методы

"..."
function f end

"..."
f

Добавляет строку документации "..." к Function f. Первый вариант является предпочтительным, однако оба эквивалентны.

"..."
f(x) = x

"..."
function f(x)
    x
end

"..."
f(x)

Добавляет строку документации "..." к Method f(::Any).

"..."
f(x, y = 1) = x + y

Добавляет строку документации "..." к двум Method , а именно f(::Any) и f(::Any, ::Any).

Макросы

"..."
macro m(x) end

Добавляет строку документации "..." к определению макроса @m(::Any).

"..."
:(@m)

Добавляет строку документации "..." к макросу с именем @m.

Типы

"..."
abstract T1

"..."
type T2
    ...
end

"..."
immutable T3
    ...
end

Добавляет строку документации "..." к типам T1, T2, и T3.

"..."
type T
    "x"
    x
    "y"
    y
end

Добавляет строку документации "..." к типу T, "x" к полю T.x и "y" к полю T.y. Также применимо к типам immutable.

"..."
typealias A T

Добавляет строку документации "..." к Binding A.

Binding используются для хранения ссылки на конкретную Symbol в Module без хранения самой ссылаемой величины.

Модули

"..."
module M end

module M

"..."
M

end

Добавляет строку документации "..." к Module M. Добавление строки документации над Module является предпочтительным синтаксисом, однако оба эквивалентны.

"..."
baremodule M
# ...
end

baremodule M

import Base: @doc

"..."
f(x) = x

end

Документирование baremodule путем размещения строки документации над выражением автоматически импортирует @doc в модуль. Эти импорты необходимо выполнять вручную, когда выражение модуля не документировано. Пустые baremodule не могут быть задокументированы.

Глобальные переменные

"..."
const a = 1

"..."
b = 2

"..."
global c = 3

Добавляет строку документации "..." к Binding a, b, и c.

"..."
f(x) = x + 1
const alias = f

f(x) = x + 1
"..."
const alias = f

"..."
sym

Добавляет строку документации "..." к значению, связанному с sym. Пользователи должны предпочитать документировать sym при его определении.

Несколько объектов

"..."
a, b

Добавляет строку документации "..." к a и b , каждое из которых должно быть документируемым выражением. Этот синтаксис эквивалентен

"..."
a

"..."
b

Любое количество выражений может быть документировано таким образом. Этот синтаксис может быть полезен, когда две функции связаны, например, не изменяющие и изменяющие версии f и f!.

Макро-генерируемый код

"..."
@m expression

Добавляет строку документации "..." к выражению, сгенерированному при разворачивании @m expression. Это позволяет документировать выражения, помеченные @inline, @noinline, @generated, или любым другим макросом, аналогично не помеченным выражениям.

Авторы макросов должны обратить внимание, что только макросы, генерирующие одно выражение, будут автоматически поддерживать строки документации. Если макрос возвращает блок, содержащий несколько подвыражений, то подвыражение, которое должно быть задокументировано, должно быть помечено с помощью макроса @__doc__().

Макро @enum использует @__doc__ для возможности документирования Enum. Изучение его определения должно служить примером правильного использования @__doc__.

@__doc__(ex)

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

macro example(f)
    quote
        $(f)() = 0
        @__doc__ $(f)(x) = 1
        $(f)(x, y) = 2
    end |> esc
end

@__doc__ не имеет эффекта, когда макрос, использующий его, не документирован.

Синтаксис Markdown

Следующий синтаксис Markdown поддерживается в Julia.

Элементы в строке

Здесь «в строке» относится к элементам, которые можно найти внутри блоков текста, т.е. абзацев. Они включают следующие элементы.

Жирный шрифт

Окружите слова двумя звёздочками, **, чтобы вывести заключённый текст жирным шрифтом.

A paragraph containing a **bold** word.

Курсив

Окружите слова одной звёздочкой, *, чтобы вывести заключённый текст курсивом.

A paragraph containing an *emphasised* word.

Литералы

Окружите текст, который должен быть показан точно так, как написан, одинарными обратными апострофами, ` .

A paragraph containing a `literal` word.

Литералы должны использоваться при написании текста, относящегося к именам переменных, функций или других частей программы Julia.

A paragraph containing a ``` `backtick` character ```.

\(\LaTeX\)

Окружите текст, который должен отображаться как математика, используя синтаксис \(\LaTeX\) с двойными обратными апострофами, `` .

A paragraph containing some ``\LaTeX`` markup.

Ссылки

Ссылки на внешние или внутренние адреса можно написать, используя следующий синтаксис, где текст в квадратных скобках, [ ], - это имя ссылки, а текст в скобках, ( ), - это URL.

A paragraph containing a link to [Julia](http://www.julialang.org).

Ссылки на сноски

Именованные и пронумерованные ссылки на сноски можно написать, используя следующий синтаксис. Имя сноски должно быть одним алфавитно-цифровым словом без знаков препинания.

A paragraph containing a numbered footnote [^1] and a named one [^named].

Элементы верхнего уровня

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

Абзацы

Абзац — это блок простого текста, который может содержать любое количество элементов в строке, определённых в разделе «Элементы в строке» выше, с одной или несколькими пустыми строками над и под ним.

This is a paragraph.

And this is *another* one containing some emphasised text.
A new line, but still part of the same paragraph.

Заголовки

Документ можно разбить на различные разделы с помощью заголовков. Заголовки используют следующий синтаксис:

# Level One
## Level Two
### Level Three
#### Level Four
##### Level Five
###### Level Six

Строка заголовка может содержать любой синтаксис в строке так же, как и абзац.

Блоки кода

Исходный код может быть показан как текстовый блок с отступом в четыре пробела, как показано в следующем примере.

This is a paragraph.

    function func(x)
        # ...
    end

Another paragraph.

Кроме того, блоки кода могут быть заключены в тройные обратные апострофы с необязательным «языком», чтобы указать, как блок кода должен быть выделен.

A code block without a "language":

```
function func(x)
    # ...
end
```

and another one with the "language" specified as `julia`:

```julia
function func(x)
    # ...
end
```

Блочные цитаты

Текст из внешних источников, например, цитаты из книг или веб-сайтов, могут быть приведены в кавычках, используя символы > перед каждой строкой цитаты, как показано ниже.

Here's a quote:

> Julia is a high-level, high-performance dynamic programming language for
> technical computing, with syntax that is familiar to users of other
> technical computing environments.

Обратите внимание, что после символа > в каждой строке должен стоять один пробел. Блоки цитат могут сами содержать другие элементы верхнего уровня или строки.

Изображения

Синтаксис изображений похож на синтаксис ссылок, упомянутый выше. Добавление символа ! к ссылке отобразит изображение из указанного URL, а не ссылку на него.

![alternative text](link/to/image.png)

Списки

Неупорядоченные списки можно написать, добавив перед каждым элементом в списке либо *, либо +, либо -.

A list of items:

  * item one
  * item two
  * item three

Обратите внимание на два пробела перед каждым * и один пробел после каждого.

Списки могут содержать другие вложенные элементы верхнего уровня, такие как списки, блоки кода или блоки цитат. Между каждым элементом списка при включении элементов верхнего уровня в список должна быть пустая строка.

Another list:

  * item one

  * item two

    ```
    f(x) = x
    ```

  * And a sublist:

      + sub-item one
      + sub-item two

Нумерованные списки записываются путём замены символа «пули», либо *, либо +, либо -, положительным целым числом, за которым следует либо . , либо ).

Two ordered lists:

 1. item one
 2. item two
 3. item three


 5) item five
 6) item six
 7) item seven

Нумерованный список может начинаться с числа, отличного от одного, как во втором списке приведенного выше примера, где нумерация начинается с пяти. Как и неупорядоченные списки, нумерованные списки могут содержать вложенные элементы верхнего уровня.

Выводимые уравнения

Крупные уравнения \(\LaTeX\), которые не помещаются в строку внутри абзаца, могут быть написаны как выводимые уравнения, используя блок кода с «языком» math, как в примере ниже.

```math
f(a) = \frac{1}{2\pi}\int_{0}^{2\pi} (\alpha+R\cos(\theta))d\theta
```

Сноски

Этот синтаксис связан с синтаксисом в строке для Ссылок на сноски. Убедитесь, что вы прочитали этот раздел тоже.

Текст сноски определяется с помощью следующего синтаксиса, который похож на синтаксис ссылки на сноску, за исключением символа :, который добавляется к метке сноски.

[^1]: Numbered footnote text.

[^note]:

    Named footnote text containing several toplevel elements.

      * item one
      * item two
      * item three

    ```julia
    function func(x)
        # ...
    end
    ```

Горизонтальные линии

Эквивалент тега <hr> HTML можно написать, используя следующий синтаксис:

Text above the line.

---

And text below the line.

Таблицы

Базовые таблицы можно создавать, используя синтаксис, описанный ниже. Обратите внимание, что таблицы Markdown имеют ограниченные возможности и не могут содержать вложенные элементы верхнего уровня в отличие от других элементов, обсуждаемых выше — разрешены только инлайновые элементы. Таблицы всегда должны содержать строку заголовка с именами столбцов. Ячейки не могут охватывать несколько строк или столбцов таблицы.

| Column One | Column Two | Column Three |
|:---------- | ---------- |:------------:|
| Row `1`    | Column `2` |              |
| *Row* 2    | **Row** 2  | Column ``3`` |

Примечания

Специально отформатированные блоки с заголовками, такими как «Примечания», «Предупреждение» или «Советы», называются примечаниями и используются, когда какая-либо часть документа требует особого внимания. Они могут быть определены с помощью следующего !!! синтаксиса:

!!! note

    This is the content of the note.

!!! warning "Beware!"

    And this is another one.

    This warning admonition has a custom title: `"Beware!"`.

Примечания, как и большинство других элементов верхнего уровня, могут содержать другие элементы верхнего уровня. Если текст заголовка, указанный после типа примечания в кавычках, отсутствует, используется тип блока, т.е. "Note" в случае примечания note.

Расширения синтаксиса Markdown

Markdown Julia поддерживает интерполяцию очень похожим образом на базовые строковые литералы, с той разницей, что он будет хранить сам объект в дереве Markdown (в отличие от преобразования его в строку). При рендеринге содержимого Markdown будут вызываться обычные show методы, и они могут быть переопределены как обычно. Этот дизайн позволяет расширять Markdown произвольно сложными функциями (такими как ссылки) без усложнения основного синтаксиса.

В принципе, сам парсер Markdown также может быть расширен произвольными пакетами, или может быть использован совершенно другой вариант Markdown, но это обычно не требуется.