go/doc（文档）

• import "go/doc"

• 概述

• 索引

概述

Package doc 从 Go AST 中提取源代码文档。

索引

• 变量

• func Examples(files ...*ast.File) []*Example

• func IsPredeclared(s string) bool

• func Synopsis(s string) string

• func ToHTML(w io.Writer, text string, words map[string]string)

• func ToText(w io.Writer, text string, indent, preIndent string, width int)

• type Example

• type Filter

• type Func

• type Mode

• type Note

• type Package

• func New(pkg *ast.Package, importPath string, mode Mode) *Package

• func (p *Package) Filter(f Filter)

• type Type

• type Value

包文件

comment.go doc.go example.go exports.go filter.go reader.go synopsis.go

变量

var IllegalPrefixes = []string{
        "copyright",
        "all rights",
        "author",
}

func Examples（显示源代码）

func Examples(files ...*ast.File) []*Example

Examples 返回按名称字段排序的文件中找到的示例。Order 字段记录遇到示例的顺序。

可播放的示例必须位于名称以“_test”结尾的包中。在以下任一情况下，示例都是“playable”（播放字段不为零）：

 - 示例函数是自包含的：函数仅引用
  来自其他包的标识符（或预先标识的标识符，例如
  “int”）并且测试文件不包含点导入。
- 整个测试文件就是一个例子：该文件只包含一个
  示例函数，零测试或基准函数，以及至少一个
  顶级函数，类型，变量或常量声明其他
  比示例函数。

func IsPredeclared（显示源代码）

func IsPredeclared(s string) bool

IsPredeclared 报告 s 是否是预先标识的标识符。

func Synopsis（显示源代码）

func Synopsis(s string) string

Synopsis 返回 s 中第一句话的清晰版本。该句在第一个句点后加空格，并且前面没有一个大写字母后结束。结果字符串没有 \n，\r 或 \t 字符，并且在单词之间只使用单个空格。如果 s 从任何非法前缀开始，则结果是空字符串。

func ToHTML（显示源代码）

func ToHTML(w io.Writer, text string, words map[string]string)

ToHTML 将注释文本转换为格式化的 HTML。该评论是由 DocReader 编写的，因此已知不会在行尾有空行，也不会在行尾有尾随空格。评论标记已被删除。

不缩进的非空行的每个跨度都被转换为单个段落。规则有一个例外：由单一行组成的跨度，后面跟着另一段跨度，以大写字母开头，并且不包含标点符号被格式化为标题。

缩进行的跨度被转换为 <pre> 块，并删除了公共缩进前缀。

评论文本中的 URL 被转换为链接；如果 URL 也出现在单词映射中，则链接将从映射中获取（如果相应的映射值是空字符串，则 URL 不会转换为链接）。

出现在单词映射中的 Go 标识符以斜体表示；如果相应的映射值不是空字符串，则将其视为 URL 并将该单词转换为链接。

func ToText（显示源代码）

func ToText(w io.Writer, text string, indent, preIndent string, width int)

ToText 以文本输出的形式准备评论文本。它将文本段落包装成宽度或更少的 Unicode 代码点，然后将每行缩进前缀。在预先格式化的部分（如程序文本）中，它使用 preIndent 前缀每个非空行。

type Example（显示源代码）

一个Example 代表了一个在源文件中找到的示例函数。

type Example struct {
        Name        string // 被例示的项目的名称
        Doc         string // 示例函数doc string
        Code        ast.Node
        Play        *ast.File // 该示例的整个程序版本
        Comments    []*ast.CommentGroup
        Output      string // 预期输出
        Unordered   bool
        EmptyOutput bool // 期待空输出
        Order       int  // 原始源代码顺序
}

type Filter（显示源代码）

type Filter func(string) bool

type Func（显示源代码）

Func 是 func 声明的文档。

type Func struct {
        Doc  string
        Name string
        Decl *ast.FuncDecl

        // 方法
        // （对于函数，这些字段具有相应的零值）
        Recv  string // 实际接收器 “T”或“* T”
        Orig  string // 原始接收器 “T”或“* T”
        Level int    // 嵌入水平; 0表示未嵌入
}

type Mode（显示源代码）

Mode 值控制 New 的操作。

type Mode int

const (
        // 提取所有包级声明的文档，
        // 不只是出口的
        AllDecls Mode = 1 << iota

        // 显示所有嵌入式方法，而不仅仅是
        // 不可见（未导出）的匿名字段
        AllMethods
)

type Note（显示源代码）

Note 代表以“MARKER(uid):note body”开头的标注注释。任何带有2个或更多大写 AZ 字母的标记以及至少一个字符的uid都被识别。uid后面的“:”是可选的。注释收集在由 Note 标记索引的 Package.Notes地图中。

type Note struct {
        Pos, End token.Pos // 包含标记的注释的位置范围
        UID      string    // 用标记找到的uid
        Body     string    // 注意正文
}

type Package（显示源代码）

Package 是整个包的文档。

type Package struct {
        Doc        string
        Name       string
        ImportPath string
        Imports    []string
        Filenames  []string
        Notes      map[string][]*Note

        // 不推荐使用：为了向后兼容性，Bugs仍然填充，
        // 但是所有新代码都应该使用Notes。
        Bugs []string

        // 声明
        Consts []*Value
        Types  []*Type
        Vars   []*Value
        Funcs  []*Func
}

func New（显示源代码）

func New(pkg *ast.Package, importPath string, mode Mode) *Package

New 计算给定包 AST 的包文档。New 取得 AST pkg 的所有权，并可以编辑或覆盖。

func (*Package) Filter（显示源代码）

func (p *Package) Filter(f Filter)

过滤器消除了不通过过滤器f的名称的文档。TODO(gri):将“Type.Method”识别为名称。

type Type（显示源代码）

Type 是类型声明的文档。

type Type struct {
        Doc  string
        Name string
        Decl *ast.GenDecl

        // 相关声明
        Consts  []*Value // 排序的（大多数）此类型的常量列表
        Vars    []*Value // 排序的（大多数）此类型的变量列表
        Funcs   []*Func  // 返回此类型的函数的排序列表
        Methods []*Func  // 排序的此类型的方法列表（包括嵌入式方法）
}

type Value（显示源代码）

Value 是（可能分组的）var 或 const 声明的文档。

type Value struct {
        Doc   string
        Names []string // 声明顺序中的var或const名称
        Decl  *ast.GenDecl
        // 包含已过滤或未导出的字段
}