ドキュメンテーション

ドキュメンテーション

パッケージ開発者やユーザーは、Julia v0.4 以降で組み込みのドキュメントシステムを使って、関数、型、およびその他のオブジェクトのドキュメンテーションを簡単に行えます。

基本的な構文は単純です: オブジェクト (関数、マクロ、型、またはインスタンス)の直前・最上位の文字列を書くと その文字列はドキュメントと解釈されます (これらは docstringsと呼ばれます)。 docstring とドキュメント化したいオブジェクトの間に、空白行やコメントがないようにしてください。基本的な例は以下の通りです:

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

ドキュメンテーションはMarkdownとして解釈されます。そのため、インデントやコードフェンスを使って、テキストとコード例を分けて書くことができます。技術的には、全てのオブジェクトをメタデータとして、別のオブジェクトに関連付けることができます。デフォルトでは、ドキュメントはマークダウンとして解釈されますが、他の文字列のマクロを定義して、@docマクロに渡してドキュメントとすることもできます。

!!! メモ Markdown サポートは Markdown 標準ライブラリで実装されています。サポートされている構文一覧は Markdownのドキュメント を参照してください

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. ドキュメントの上部に関数のシグネチャを常に表示し、スペース4つのインデントを使用して、Julia コードとして印刷します。

    ここでの表記は、Juliaコードのシグネチャと全く同じにしてもよいですし (mean(x::AbstractArray)などのように)、簡略表記としてもよいしょう。 オプション引数は、可能な場合は実際のJuliaの構文に従って、デフォルト値も示すべきです(つまりf(x, y=1)のように)。 デフォルト値を持たないオプション引数は、括弧内に入れてください (つまり、f(x[,y])や f(x[,y[,z]]のように)。 その他の方法としては、複数行を使用することです: 1行を通常引数に、ほかの行をオプション引数に使う、ということです。 この方法は、ある関数に対して、いくつかの関連するメソッドのドキュメンテーションにも使用ですまう。 関数が多くのキーワード引数を持つ時には、<keyword arguments>プレースホルダのみをシグネチャに含むシグネチャに含めて (すなわちf(x;<keyword arguments>))、完全な引数リストを #Arguments セクション以下に書いてください(ポイント4参照)。

  2. 簡略化されたシグニチャの後には、関数の振る舞い、やオブジェクトが何者であるか、1行で説明しましょう 必要に応じて、1行空けたあとの段落でより詳細について記述してください。

    関数の1 行説明は、3単現のsを付けずに、命令形で書いてください。最後にピリオドを付けます。 関数の意味を簡単に要約できない場合は、関数の構成要素を分割するとよいかもしれません(絶対的な要件ではなく、あくまで一例です)。

  3. 繰り返しを避けましょう(DRY)。

    関数名はシグネチャによって与えられるので、「関数barは..」という文言でドキュメントを開始する必要はありません: はじめから要点を書いてください。同様に、シグネチャで引数の型が指定されているならば、説明で型に言及することは冗長です。

  4. 本当に必要な場合にのみ引数リストを書きます。

    単純な関数の場合、関数の目的を説明する際に直接 引数の役割に言及する方が明らかにわかりやすいことがあります。 (そのような場合、)引数リストは、他の場所で言及された情報を繰り返すだけです ただし、多くの引数(特にキーワード引数)を使う、複雑な関数に対しては、引数リストを書くのはよいアイディアです。 その場合、一般的な関数説明の後、#Arguments ヘッダの下に引数リストを挿入します。引数1つずつに対して - の箇条書きを使いましょう。 リストには、引数の型と既定値 (ある場合) を指定する必要があります。

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

  5. 関連する関数にヒント(see. also)を加えましょう。

    関連する機能をもつ関数がある場合は、適切な関数を発見して貰う可能性を高めるために、See also: の段落でに関連する関数の短いリストを加えましょう。

    See also: [`bar!`](@ref), [`baz`](@ref), [`baaz`](@ref)

  6. # Examplesセクションになんからのコード例を示しましょう。

    例は、可能な限り doctestsとして記述する必要があります。doctest はフェンスで囲まれたコードブロックです(コードブロック 参照) 。 ```jldoctestで始まり、任意の数の julia> プロンプトが、その入出力とともに含まれます。ここでの出力はJuliaのREPLであれば与えられた入力に対して、この出力を出すだろうという期待値です。

    !!!メモ doctest はDocumenter.jlによって有効化されます。 詳細なドキュメントについては、Documenter のマニュアルを見てください。

    たとえば、次の docstring では変数 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 およびその他の RNG 関連の関数の呼び出しは、doctest では避けて下さい。 RNG関連の関数は、異なる Julia セッションで一貫した出力を生成しないからです。何らかの乱数生成関連の機能を示したい場合の一つの選択肢は、MersenneTwister(もしくはその他の疑似乱数生成の関数)に明示的にシードを与え、その結果をdoctest を書いている関数に与えることです。

    オペレーティング システムのワードサイズ ([`Int32`](@ref) または [`Int64`](@ref))とパス区切り記号の違い
(`/` または `\`) は、一部のdoctestの再現性にも影響します。

doctest の空白は重要です。doctest は例えば配列のpritty-printの出力位置が(期待値と)ずれていると失敗します。

    JuliaのマニュアルとAPIドキュメントではコードexampleが確実に機能します。 すべてのdoctestを実行するには make -C doctest=trueを実行してください

    出力結果が切り捨てられることを示すには、チェックを停止すべき行で[...]と書くことができます。 これは、doctest で何か例外がスローされたとき、スタックトレース(これは、Julia のコード行への非永続的な参照を含みます) を非表示にするのに役立ちます。例えば:

    ```jldoctest
julia> div(1, 0)
ERROR: DivideError: integer division error
[...]
```

    Examples that are untestable should be written within fenced code blocks starting with ```julia so that they are highlighted correctly in the generated documentation.

    Tip

    Wherever possible examples should be self-contained and runnable so that readers are able to try them out without having to include any dependencies.

  7. Use backticks to identify code and equations.

    Julia identifiers and code excerpts should always appear between backticks ` to enable highlighting. Equations in the LaTeX syntax can be inserted between double backticks ``. Use Unicode characters rather than their LaTeX escape sequence, i.e. ``α = 1`` rather than ``\\alpha = 1``.

  8. Place the starting and ending """ characters on lines by themselves.

    That is, write:

    """
...

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

    rather than:

    """...

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

    This makes it more clear where docstrings start and end.

  9. Respect the line length limit used in the surrounding code.

    Docstrings are edited using the same tools as code. Therefore, the same conventions should apply. It is advised to add line breaks after 92 characters.

  10. Provide information allowing custom types to implement the function in an # Implementation section. These implementation details intended for developers rather than users, explaining e.g. which functions should be overridden and which functions automatically use appropriate fallbacks, are better kept separate from the main description of the function's behavior.

ドキュメントへのアクセス

Documentation can be accessed at the REPL or in IJulia by typing ? followed by the name of a function or macro, and pressing Enter. For example,

?cos
?@time
?r""

will bring up docs for the relevant function, macro or string macro respectively. In Juno using Ctrl-J, Ctrl-D will bring up documentation for the object under the cursor.

関数とメソッド

Functions in Julia may have multiple implementations, known as methods. While it's good practice for generic functions to have a single purpose, Julia allows methods to be documented individually if necessary. In general, only the most generic method should be documented, or even the function itself (i.e. the object created without any methods by function bar end). Specific methods should only be documented if their behaviour differs from the more generic ones. In any case, they should not repeat the information provided elsewhere. For example:

"""
    *(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.

When retrieving documentation for a generic function, the metadata for each method is concatenated with the catdoc function, which can of course be overridden for custom types.

高度な使い方

The @doc macro associates its first argument with its second in a per-module dictionary called META.

To make it easier to write documentation, the parser treats the macro name @doc specially: if a call to @doc has one argument, but another expression appears after a single line break, then that additional expression is added as an argument to the macro. Therefore the following syntax is parsed as a 2-argument call to @doc:

@doc raw"""
...
"""
f(x) = x

This makes it possible to use expressions other than normal string literals (such as the raw"" string macro) as a docstring.

When used for retrieving documentation, the @doc macro (or equally, the doc function) will search all META dictionaries for metadata relevant to the given object and return it. The returned object (some Markdown content, for example) will by default display itself intelligently. This design also makes it easy to use the doc system in a programmatic way; for example, to re-use documentation between different versions of a function:

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

Or for use with Julia's metaprogramming functionality:

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

Documentation written in non-toplevel blocks, such as begin, if, for, and let, is added to the documentation system as blocks are evaluated. For example:

if condition()
    "..."
    f(x) = x
end

will add documentation to f(x) when condition() is true. Note that even if f(x) goes out of scope at the end of the block, its documentation will remain.

動的ドキュメント

Sometimes the appropriate documentation for an instance of a type depends on the field values of that instance, rather than just on the type itself. In these cases, you can add a method to Docs.getdoc for your custom type that returns the documentation on a per-instance basis. For instance,

struct MyType
    value::String
end

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

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

?x will display "Documentation for MyType with value x" while ?y will display "Documentation for MyType with value y".

構文ガイド

A comprehensive overview of all documentable Julia syntax. In the following examples "..." is used to illustrate an arbitrary docstring.

$ and \ characters

The $ and \ characters are still parsed as string interpolation or start of an escape sequence in docstrings too. The raw"" string macro together with the @doc macro can be used to avoid having to escape them. This is handy when the docstrings include LaTeX or Julia source code examples containing interpolation:

@doc raw"""
```math
\LaTeX
```
"""
function f end

関数とメソッド

"..."
function f end

"..."
f

Adds docstring "..." to the function f. The first version is the preferred syntax, however both are equivalent.

"..."
f(x) = x

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

"..."
f(x)

Adds docstring "..." to the method f(::Any).

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

Adds docstring "..." to two Methods, namely f(::Any) and f(::Any, ::Any).

マクロ

"..."
macro m(x) end

Adds docstring "..." to the @m(::Any) macro definition.

"..."
:(@m)

Adds docstring "..." to the macro named @m.

型

"..."
abstract type T1 end

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

"..."
struct T3
    ...
end

Adds the docstring "..." to types T1, T2, and T3.

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

Adds docstring "..." to type T, "x" to field T.x and "y" to field T.y. Also applicable to mutable struct types.

モジュール

"..."
module M end

module M

"..."
M

end

Adds docstring "..." to the ModuleM. Adding the docstring above the Module is the preferred syntax, however both are equivalent.

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

baremodule M

import Base: @doc

"..."
f(x) = x

end

Documenting a baremodule by placing a docstring above the expression automatically imports @doc into the module. These imports must be done manually when the module expression is not documented. Empty baremodules cannot be documented.

グローバル変数

"..."
const a = 1

"..."
b = 2

"..."
global c = 3

Adds docstring "..." to the Bindings a, b, and c.

Bindings are used to store a reference to a particular Symbol in a Module without storing the referenced value itself.

Note

When a const definition is only used to define an alias of another definition, such as is the case with the function div and its alias ÷ in Base, do not document the alias and instead document the actual function.

If the alias is documented and not the real definition then the docsystem (? mode) will not return the docstring attached to the alias when the real definition is searched for.

For example you should write

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

rather than

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

Adds docstring "..." to the value associated with sym. Users should prefer documenting sym at its definition.

Multiple Objects

"..."
a, b

Adds docstring "..." to a and b each of which should be a documentable expression. This syntax is equivalent to

"..."
a

"..."
b

Any number of expressions many be documented together in this way. This syntax can be useful when two functions are related, such as non-mutating and mutating versions f and f!.

Macro-generated code

"..."
@m expression

Adds docstring "..." to expression generated by expanding @m expression. This allows for expressions decorated with @inline, @noinline, @generated, or any other macro to be documented in the same way as undecorated expressions.

Macro authors should take note that only macros that generate a single expression will automatically support docstrings. If a macro returns a block containing multiple subexpressions then the subexpression that should be documented must be marked using the @__doc__ macro.

The @enum macro makes use of @__doc__ to allow for documenting Enums. Examining its definition should serve as an example of how to use @__doc__ correctly.

Core.@__doc__ — Macro.
@__doc__(ex)

Low-level macro used to mark expressions returned by a macro that should be documented. If more than one expression is marked then the same docstring is applied to each expression.

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

@__doc__ has no effect when a macro that uses it is not documented.

source