Go scanner.Scanner 的 ScanComments 和 SkipComments 有什么区别

如果你在 Go 里看到 ScanComments 和 SkipComments，先记住一个容易混淆的点：这两个名字属于 text/scanner，不是 go/scanner。前者是面向 UTF-8 文本的通用扫描器，后者是 Go 源码扫描器；go/scanner 的公开模式里只有 ScanComments，没有 SkipComments。

官方文档：https://pkg.go.dev/text/scanner#Mode

在 text/scanner 中，ScanComments 决定“要不要把注释识别成注释”，SkipComments 决定“识别之后要不要直接跳过”。因此常见组合是：需要拿到注释文本时使用 ScanComments 并清除 SkipComments；只想扫描代码 token 时直接使用默认的 scanner.GoTokens。

先把两个 scanner 包分开

这次问题的标题写成了 scanner.Scanner，但 Go 标准库中有两个容易被简称为 scanner 的包。

所以，如果代码导入的是 text/scanner，就可以讨论这两个模式位的组合；如果导入的是 go/scanner，应该围绕它的 Mode 和 ScanComments 说明注释是否返回，不能凭记忆补出一个不存在的 go/scanner.SkipComments。

理解 ScanComments 与 SkipComments 的分工

ScanComments 是入口开关。扫描器只有在这个位打开时，才会把以 // 或 /* 开头的内容按注释处理。

SkipComments 是处理策略。它和 ScanComments 一起打开时，注释会被消费掉，下一次 Scan 直接从后面的 token 继续；如果清除了 SkipComments，注释会以 scanner.Comment 返回，原始文本可以通过 TokenText() 取出。

官方源码中的判断顺序也说明了这个关系：先检查 ScanComments，再检查 SkipComments。因此只设置 SkipComments 而不设置 ScanComments，并不能得到“跳过已识别注释”的效果，斜杠会按未识别注释的普通字符路径继续处理。

从零构建一个注释 token 检查器

为了避免只背结论，可以做一个很小的命令行程序：同一份输入分别使用“跳过注释”和“保留注释”两种模式，把 token 名称与文本打印出来。这里不需要 AST，也不需要把输入先拆成多行。

package main

import (
    "fmt"
    "strings"
    "text/scanner"
)

// dumpTokens 根据 keepComments 选择是否保留注释 token。
func dumpTokens(label, src string, keepComments bool) {
    var s scanner.Scanner
    s.Init(strings.NewReader(src))

    // GoTokens 默认包含 ScanComments 和 SkipComments，先得到完整的 Go token 集合。
    s.Mode = scanner.GoTokens
    if keepComments {
        // 清除跳过位，但保留识别位，注释就会以 scanner.Comment 返回。
        s.Mode &^= scanner.SkipComments
    }

    fmt.Println(label)
    for tok := s.Scan(); tok != scanner.EOF; tok = s.Scan() {
        // TokenText 返回最近一次 Scan 得到的原始 token 文本。
        fmt.Printf("%-8s %q\\n", scanner.TokenString(tok), s.TokenText())
    }
}

func main() {
    const src = `package demo // 行尾注释
var n = 1 /* 块注释 */`

    // 两次扫描使用同一输入，只改变注释保留策略。
    dumpTokens("skip comments", src, false)
    dumpTokens("keep comments", src, true)
}

这个程序的关键不在打印格式，而在这一行：s.Mode &^= scanner.SkipComments。&^ 是按位清除，意味着保留 GoTokens 中的其他 token 能力，只关闭“跳过注释”这一项。因为 ScanComments 仍然存在，扫描器会继续把注释识别为注释 token。

用输出差异确认模式是否生效

在 skip comments 这一组中，输出会从 package、demo 等普通 token 直接跳过注释；注释文本不会出现在 TokenText() 的结果里。这里的“跳过”不是把字符改掉，而是扫描器消费注释后重新寻找下一个 token。

在 keep comments 这一组中，遇到 // 行尾注释 或 /* 块注释 */ 时，scanner.TokenString(tok) 会得到 Comment，TokenText() 会得到包含注释标记的原始文本。行注释的换行不属于注释文本本身，块注释则会整体作为一个注释 token 处理。

如果你的工具只收集注释，例如提取文档片段或统计注释位置，建议显式写出保留策略，而不要依赖某个版本或示例中的默认值：

var s scanner.Scanner
s.Init(strings.NewReader(src))

// 只保留 Go token 集合中的识别能力，同时让注释作为 token 返回。
s.Mode = scanner.GoTokens &^ scanner.SkipComments
for tok := s.Scan(); tok != scanner.EOF; tok = s.Scan() {
    // 只处理注释，其他 token 继续被扫描但不进入结果。
    if tok == scanner.Comment {
        fmt.Println(s.TokenText())
    }
}

几个容易写错的组合

• 把两个包混为一谈：text/scanner.SkipComments 不能直接替换成 go/scanner.SkipComments。先看 import 路径，再决定 API。
• 只设置 SkipComments：它的跳过逻辑依赖 ScanComments 已经打开。需要“跳过已识别注释”时，通常从 scanner.GoTokens 开始最稳妥。
• 保留注释后忘记读取 TokenText：tok == scanner.Comment 只告诉你 token 类型，具体注释内容还要在这次 Scan 后读取 s.TokenText()。
• 扫描过程中随意改变 Mode：Mode 可以改变，但为了让一轮扫描的语义稳定，最好在开始扫描前完成组合；如果确实动态切换，要明确切换点和后续 token 的解释。

项目验收与选择建议

把这个小工具接入实际代码时，可以用下面的判断表做最后选择：

最终可以把结论压缩成一句话：ScanComments 决定“认不认识注释”，SkipComments 决定“认识后留不留在 token 流里”。需要保留注释时，使用 text/scanner 并清除 SkipComments；需要 Go 源码位置和 token.File 语义时，再切换到 go/scanner 的 API。

相关问题

SkipComments 默认是打开的吗？

使用 text/scanner 的 GoTokens 时是打开的，所以默认会跳过注释。想拿到注释 token，需要清除这个位。

清除 SkipComments 后还需要保留 ScanComments 吗？

需要。清除跳过位只改变处理策略，必须同时保留 ScanComments 才会把注释识别成 Comment。

go/scanner 怎么保留注释？

使用 go/scanner 时打开它的 ScanComments 模式，并按该包的 Scanner.Scan 返回值处理注释；不要引用不存在的 go/scanner.SkipComments。