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

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

отобразят документацию по соответствующей функции, макросу и строковому макросу. В большинстве сред Julia существует способ обратиться к документации напрямую.

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

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

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

Вот более сложный пример по-прежнему на основе Markdown:

В примере выше продемонстрирован ряд простых стандартов, которым рекомендуется следовать при написании документации.

Для этого нужно использовать символы Юникода, а не escape-последовательность LaTeX, т. е. ``α = 1`` , а не ``\\alpha = 1``.

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

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

Макрос @doc связывает содержимое своего первого аргумента со вторым аргументом и помещает его в словарь META для конкретных модулей.

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

Это позволяет использовать в качестве docstring не только обычные строковые литералы, но и другие выражения (например, строку макроса raw"").

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

Пример использования с функциями метапрограммирования Julia:

При записи документации не в блоках верхнего уровня, например внутри begin, if, for или let, она добавляется в систему по мере обработки этих блоков. Пример:

Этот код добавляет документацию для f(x), когда условие condition() выполняется (true). При этом, даже если функция f(x) выходит за границы области после блока, ее документация сохраняется.

Для упрощения создания документации можно использовать возможности метапрограммирования. При использовании интерполяции строк внутри docstring необходим дополнительный символ $, как показано для $($name):

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

В следующих примерах "..." соответствует произвольным строкам docstring.