コメントとドキュメント

コメントとドキュメント#

コメント#

コード内の通常のコメントには // を使います：

// Explain why this branch exists.
let retries = 3

トップレベルブロックの先頭で ///| をよく見かけることもあります。これは トップレベル項目を明示的に区切るための空のドキュメントコメント行です。これは現時点のドキュメントツールにとって重要であり、将来のキャッシュやその他のツール用途に向けても、トップレベルブロックの境界を明確に保ちます。実際には、///| は通常の MoonBit コードでもドキュメントソースでも役立ちます。

ドキュメントコメント#

ドキュメントコメントは、fn、let、enum、struct、type などのトップレベル項目の直前の各行に /// を使って書きます。ドキュメントコメントは Markdown で記述します。

/// Return a new array with reversed elements.
fn[T] reverse(xs : Array[T]) -> Array[T] {
  ...
}

mbt check とマークされたドキュメントコメント内の Markdown コードブロックは、ドキュメントテストとして扱われます。moon check と moon test はこれらのテストを自動的に検査・実行するため、ドキュメントコメント内の例を常に最新に保てます。テストブロックにしたい場合は、スニペットを test { .. } で囲んでください：

/// Increment an integer by one,
///
/// Example:
/// ```mbt check
/// test {
///   inspect(incr(41), content="42")
/// }
/// ```
pub fn incr(x : Int) -> Int {
  x + 1
}

コードスニペットをドキュメントテストとして扱わせたくない場合は、Markdown コードブロックに mbt check 以外の言語 ID を付けてください：

/// `c_incr(x)` is the same as the following C code:
/// ```c
/// x++
/// ```
pub fn c_incr(x : Ref[Int]) -> Int {
  let old = x.val
  x.val += 1
  old
}

現在、ドキュメントテストは常に ブラックボックステスト として扱われます。そのため、private な定義にはドキュメントテストを付けられません。

リテラテ .mbt.md ファイル#

MoonBit は .mbt.md で終わるリテラテ Markdown ファイルもサポートします。これらのファイルは、パッケージ内で検査済みドキュメントとして置くことも、moon check と moon test の単独ファイル入力として使うこともできます。

単独ファイルの場合は、次を実行します：

moon check README.mbt.md
moon test README.mbt.md

プロジェクト内では、引き続きパッケージ単位の moon check と moon test コマンドを使ってください。

コードフェンスの言語によって、各ブロックの扱いが決まります：

  • mbt: コンパイルされるが、テストエントリは作成しない MoonBit コード

  • mbt check: MoonBit のドキュメントテストコード。アサーションを使いたいときは、ブロック内で test { .. } または async test を使います。

  • mbt nocheck: コンパイルもテストもしない MoonBit コードを表示する

  • moonbit: ドキュメント用の通常の表示コードブロック。コンパイルもテストもされません。

例えば：

```mbt nocheck
///|
fn helper() -> Int {
  42
}
```

```mbt check
///|
test "forty two" {
  inspect(40 + 2, content="42")
}
```

```mbt nocheck
///|
fn native_only() -> Unit {
  ...
}
```

単独の .mbt.md ファイルでは、front matter を使って import や対象バックエンドを指定することもできます：

---
moonbit:
  import:
    - path: moonbitlang/core/ref
      alias: ref
  backend:
    native
---

```mbt check
fn answer() -> Int {
  let cell : @ref.Ref[Int] = { val: 41 }
  cell.val + 1
}

///|
test "answer" {
  inspect(answer(), content="42")
}
```

ファイルが直接 import できるパッケージを明示したい場合は moonbit.import を使います。モジュール依存関係だけを宣言して、Moon に import を自動生成させたい場合は moonbit.deps を使います。

目次