Writing jldoctests

このページでは、ドキュメント内のjldoctestブロックの記述と保守の方法を説明します。以下のガイドラインに従うことで、doctestの信頼性を保ち、読みやすくできます。

Filters

実行ごとに変わる可能性のあるテキストが出力に含まれる場合は、必ずfilter =を使用してください。よくある例を以下に示します。

  • 出力に未定義のメモリを含む配列が含まれる(例:undefまたはsimilarによるもの)
  • 出力に乱数が含まれる
  • 出力に時間情報が含まれる
  • 出力にファイルシステムのパスが含まれる

Common filter sequences

ドキュメントでは、繰り返し使われるいくつかのパターンを利用しています。

  • r"int.jl:\\d+" — 内省マクロから行番号を取り除く。
  • r"Stacktrace:(\\n \\[0-9]+\\].*)*" — エラーの例を示す際にスタックトレースを隠す。
  • r"Closest candidates.*\\n .*" — MethodErrorが出力するメソッド候補をスキップする。
  • r"@ .*" — methodsまたは@whichの出力からファイルの場所を取り除く。
  • r"\\@world\\(MyStruct, \\d+:\\d+\\)" — world ageの数値をフィルタリングする。
  • r"with \\d+ methods" — 関数を再定義する際のメソッド数を無視する。
  • r"[0-9\\.]+ seconds \\(.*?\\)" — メモリ情報を含む時間計測の出力を取り除く。
  • r"[0-9\\.]+ seconds" — 単純な時間計測結果を取り除く。
  • r"[0-9\\.]+" — 無名関数などの名前に含まれる数字をフィルタリングする。
  • r"([A-B] [0-5])"およびr"[A-B] [X-Z] [0-5]" — プロセス出力の非決定性に対応する。
  • r"(world\\nhello|hello\\nworld)" — 交互に出力される内容の順序をどちらでも許容する。

どれも当てはまらない場合は、変動するテキストを取り除く正規表現を作成してください。フィルターを使うと、プラットフォームやJuliaのバージョンが異なってもdoctestを安定させられます。

docstring内での二重エスケープ

docstring内に正規表現フィルターを書く場合は、バックスラッシュを二重にエスケープする必要があります。たとえば、r"[\d\.]+"ではなくr"[\\d\\.]+"を使用してください。正規表現が作成される前に、docstring自体がエスケープシーケンスを処理するためです。

Setup code

簡単なセットアップ式は、setup =オプションを使ってインラインで記述できます。

```jldoctest; setup = :(using InteractiveUtils)
...
```

セットアップコードが長い場合や、複数のブロックで同じ環境が必要な場合は、DocTestSetupメタブロックを使用してください。

```@meta
DocTestSetup = :(import Random; Random.seed!(1234))
```

その後、次のようにして無効にします。

```@meta
DocTestSetup = nothing
```

Teardown code

作成した一時ファイルの削除やカレントディレクトリのリセットなど、後処理コードが必要な場合は、teardown =オプションを使用できます。

```jldoctest; setup = :(oldpath = pwd(); cd(mktempdir())), teardown = :(cd(oldpath))
...
```

Maintaining state between snippets

関連するdoctestブロックは、jldoctestキーワードの後に同じラベルを指定することで、状態を共有できます。マニュアルでは、変更操作を示すためにこのパターンを使用しています。

```jldoctest mutation_vs_rebind
julia> a = [1,2,3]
...
```

続いて、次のように記述します。

```jldoctest mutation_vs_rebind
julia> a[1] = 42
...
```

同じ名前のブロックはdoctestの実行時に順番に実行されるため、最初のブロックで作成した変数は後続のブロックでも使用できます。

スニペットの結果を後の例でも使う必要がある場合は、ラベルを付けて同じラベルを再利用してください。セットアップコードの重複を避けられ、REPLでの操作にも近い形になります。

Further reading

doctest構文の詳細については、corresponding Documenter.jl docsを参照してください。