文档注解

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)
}