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

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-repl
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.

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

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

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

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

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

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

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

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

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

   Подсказка

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

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

   Идентификаторы и фрагменты кода Julia всегда должны быть заключены в обратные кавычки ` для обеспечения выделения. Уравнения в синтаксисе LaTeX можно вставлять между двойными обратными кавычками ``. Используйте символы Юникода вместо их последовательностей escape 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). Конкретные методы должны документироваться только в том случае, если их поведение отличается от более общих. В любом случае, они не должны повторять информацию, предоставленную где-либо еще. Например:

"""
    *(x, y, z...)

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

"""
    *(x::AbstractString, y::AbstractString, z::AbstractString...)

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

help?> *
search: * .*

  *(x, y, z...)

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

  *(x::AbstractString, y::AbstractString, z::AbstractString...)

  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

Документация, написанная в неглобальных блоках, таких как begin, if, for, и let, добавляется к системе документации по мере оценки блоков. Например:

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

будет добавлять документацию к f(x), когда условие true истинно. Обратите внимание, что даже если f(x) выходит из области видимости в конце блока, его документация останется.

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

Иногда подходящая документация для экземпляра типа зависит от значений полей этого экземпляра, а не только от самого типа. В этих случаях вы можете добавить метод к Docs.getdoc для вашего пользовательского типа, который возвращает документацию на основе экземпляра. Например,

struct MyType
    value::String
end

Docs.getdoc(t::MyType) = "Documentation for MyType with value $(t.value)"

x = MyType("x")
y = MyType("y")

?x отобразит "Документация для MyType со значением x", а ?y отобразит "Документация для MyType со значением y".

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

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

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

"..."

doc"..."

"""
...
"""

doc"""
...
"""

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

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

"..."
function f end

"..."
f

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

"..."
f(x) = x

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

"..."
f(x)

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

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

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

Макросы

"..."
macro m(x) end

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

"..."
:(@m)

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

Типы

"..."
abstract type T1 end

"..."
mutable struct T2
    ...
end

"..."
struct T3
    ...
end

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

"..."
struct T
    "x"
    x
    "y"
    y
end

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

Модули

"..."
module M end

module M

"..."
M

end

Добавляет строку документации "..." к ModuleM. Предпочтительным синтаксисом является добавление строки документации над 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.

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

"..."
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__.

Core.@__doc__Макрос

@__doc__(ex)

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

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

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

Синтаксис Markdown

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

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

Здесь "в строке" относится к элементам, которые могут быть найдены внутри блоков текста, т.е. абзацев. К ним относятся следующие элементы.

Жирный шрифт

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

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).

Также возможно добавление перекрестных ссылок на другие документированные функции/методы/переменные внутри документации Julia. Например:

"""
    eigvals!(A,[irange,][vl,][vu]) -> values

Same as [`eigvals`](@ref), but saves space by overwriting the input `A`, instead of creating a copy.
"""

Это создаст ссылку в сгенерированной документации на документацию eigvals (которая содержит больше информации о том, что эта функция фактически делает). Хорошо включать перекрестные ссылки на изменяющие/неизменяющие версии функции или выделять разницу между двумя похожими функциями.

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

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

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, но это обычно не требуется.