文件註解

Navi 支援特殊註釋標籤來為聲明附加文件。這些註解被 LSP（用於懸停提示和補全）和文件產生器使用。

支援 //@tag 和 // @tag（// 後有空格）兩種格式。

可用標籤

標籤	位置	描述
@description	檔案頭部（任何聲明之前）	為函式庫添加頂層描述
@function	函式聲明上方	為函式添加自訂描述
@param	函式聲明上方	為參數添加描述。指定參數名稱，然後是描述
@returns	函式聲明上方	為傳回值添加描述
@type	類型或 newtype 聲明上方	為類型添加自訂描述
@enum	枚舉聲明上方	為枚舉添加自訂描述
@field	類型或枚舉聲明上方	為欄位或變體添加描述。指定欄位名稱，然後是描述
@variable	變數聲明上方	為變數添加自訂描述
@example	函式或類型聲明上方	開啟一個程式碼範例區塊（由 @endexample 關閉）
@endexample	關閉 @example 區塊	—

所有標籤支援多行續寫：緊跟在標籤行之後以 // 開頭（不帶 @ 標籤）的行會被追加到該標籤的文字中。

文件化函式

使用 @function、@param 和 @returns 來文件化函式聲明：

//@function Outputs a label with `labelText` on the bar's high.
//@param labelText (series string) The text to display on the label.
//@returns The drawn label ID.
export fn drawLabel(labelText: string) {
    label.new(bar_index, high, text:  labelText)
}

@param 和 @returns 可以出現在 @function 標籤之前或之後：

//@param series Series of values to process.
//@param length Number of bars (length).
//@function Arnaud Legoux Moving Average.
//
// It uses Gaussian distribution as weights for moving average.
export fn alma(series: series float, length: simple int): series float {
    _
}
// ...

多行描述

續寫行（以 // 開頭但不帶 @）會擴展前一個標籤的描述：

//@function Calculates the percentage difference
// from the base price to the target price.
//@param basePrice The start price
// used as the reference point.
//@param price The end price.
//@returns The signed deviation percentage.
export fn calcDeviation(basePrice: float, price: float) {
    100 * (price - basePrice) / basePrice
}

文件化類型

使用 @type 和 @field 來文件化類型聲明：

//@type A point on a chart.
//@field index The index of the bar where the point is located, i.e., its `x`
//             coordinate.
//@field price The price where the point is located, i.e., its `y` coordinate.
struct Point {
    int index,
    float price,
}

@type 標籤也適用於 newtype 聲明：

//@type Handle for a label drawing object.
export type label = int;

文件化枚舉

使用 @enum 和 @field 來文件化枚舉聲明及其變體：

//@enum Represents a trading direction.
//@field Long  A long (buy) direction.
//@field Short A short (sell) direction.
//@field Both  Both directions.
export enum Direction {
    Long,
    Short,
    Both,
}

文件化變數

使用 @variable 來文件化變數聲明：

//@variable The highest price over the last 20 bars.
float highest20 = ta.highest(high, 20)

//@variable Tracks cumulative volume since the session started.
var float cumVol = 0.0

程式碼範例

使用 @example / @endexample 對為函式或類型附加可執行的程式碼範例。區塊內每行是普通的 // 註釋，// （含空格）前綴會自動剝除。允許多個區塊，每個區塊成為一個獨立的範例。

//@function 計算兩個價格之間的百分比偏差。
//@param base  參考價格。
//@param price 目標價格。
//@returns 帶符號的偏差百分比。
//@example
// // 將今日收盤價與昨日收盤價比較
// deviation = calcDeviation(close[1], close)
// plot(deviation, title: "偏差 %")
//@endexample
export fn calcDeviation(base: float, price: float) {
    100 * (price - base) / base
}

多個範例分別用獨立的區塊包裹：

//@function 傳回 `src` 在 `length` 根 K 線上的簡單移動平均值。
//@example
// // 基本的 20 根 K 線 SMA
// plot(ta.sma(close, 20))
//@endexample
//@example
// // 使用兩條 SMA 的交叉訊號
// fast = ta.sma(close, 9)
// slow = ta.sma(close, 21)
// plot_shape(ta.crossover(fast, slow), style: Shape.LabelUp)
//@endexample
export series float sma(series float src, simple int length) => ...

範例會顯示在 VS Code 的 LSP 懸停提示中。

交叉引用連結

在任何描述文字中，可以用 [`name`] 語法建立指向其他符號的交叉引用連結。在 API 參考對話框和產生的文件頁面中，這些連結會渲染為可點擊的導航連結。

//@type Handle for a plot created by [`func:plot`].
export type plot = int;
//@function Fills the area between two [`func:plot`] handles.
//@param hline1 The first horizontal line handle (from [`func:hline`]).
//@returns An hline handle that can be used with [`fill`].

語法：

語法	解析目標
[`fill`]	當前模組的 fill，或 prelude 的 fill，或全域搜尋
[`BarmergeGaps.Off`]	BarmergeGaps.Off（枚舉成員）
[`LineStyle.Solid`]	LineStyle 列舉的 Solid 變體（連結到列舉型別）
[`variant:LineStyle.Solid`]	顯式指定列舉變體（目標相同，語意更明確）
[`func:plot`]	plot 函式（排除 plot 型別）
[`type:hline`]	hline 型別（排除 hline 函式）
[`enum:LineStyle`]	名為 LineStyle 的列舉

限定符前綴（func、type、enum）用於區分同一模組中同名的函式和型別。

對於帶點的引用，解析器首先檢查左側是否為模組並以右側作為成員名查找；未找到時再檢查左側是否為列舉型別且右側為其變體名——此時連結將導向對應的列舉型別。因此 [`BarmergeGaps.Off`]（枚舉變體）和 [`LineStyle.Solid`]（列舉變體）均可正確解析。

編輯器支援

當存在文件註解時，Navi LSP 使用它們提供：

• 懸停資訊 — 懸停在符號上時顯示描述、參數、傳回值和欄位文件
• 補全詳情 — 在自動補全建議中顯示摘要
• 文件符號 — 在大綱檢視中包含摘要

函式庫文件

對於匯出的函式庫，文件註解尤其重要。文件產生器（navi-docgen）擷取這些註解來產生 API 參考頁面。

使用 @description 在檔案頭部為函式庫本身添加頂層描述。它必須出現在任何聲明之前：

//@description 提供用於計算波動率區間的工具函式。
//
// 包含可自訂的布林通道和肯特納通道。
library("MyLib")

完整範例：

library("MyLib");

//@type Configuration for a custom indicator.
//@field length     The lookback period.
//@field multiplier The standard deviation multiplier.
export struct Config {
    int length = 14;
    float multiplier = 2.0;
}

//@function Calculates a custom band around a moving average.
//@param src    The source series.
//@param config The indicator configuration.
//@returns The upper band value.
export fn upperBand(src: series float, config: Config) {
    let basis = ta.sma(src, config.length);
    basis + config.multiplier * ta.stdev(src, config.length)
}