doc

Documentation

Overview

Package doc はGo ASTからソースコードのドキュメンテーションを取得します。

Index

• Variables
• func IsPredeclared(s string) bool
• func Synopsis(text string) string
• func ToHTML(w io.Writer, text string, words map[string]string)
• func ToText(w io.Writer, text string, prefix, codePrefix string, width int)
• type Example
  • func Examples(testFiles ...*ast.File) []*Example
• type Filter
• type Func
• type Mode
• type Note
• type Package
  • func New(pkg *ast.Package, importPath string, mode Mode) *Package
  • func NewFromFiles(fset *token.FileSet, files []*ast.File, importPath string, opts ...any) (*Package, error)
  • func (p *Package) Filter(f Filter)
  • func (p *Package) HTML(text string) []byte
  • func (p *Package) Markdown(text string) []byte
  • func (p *Package) Parser() *comment.Parser
  • func (p *Package) Printer() *comment.Printer
  • func (p *Package) Synopsis(text string) string
  • func (p *Package) Text(text string) []byte
• type Type
• type Value

Examples

• NewFromFiles

Variables

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

IllegalPrefixesは、ドキュメントコメントではないコメントを識別するための小文字の接頭辞のリストです。 これにより、パッケージ文の直前にある著作権表示のよくある間違いをドキュメントコメントと誤解しないようにします。

Functions

func IsPredeclared

func IsPredeclared(s string) bool

IsPredeclaredは、sが事前に宣言された識別子であるかどうかを報告します。

func Synopsis

func Synopsis(text string) string

Synopsisはtextの最初の文のクリーニングされたバージョンを返します。

Deprecated: 新しいプログラムは代わりに[Package.Synopsis]を使用するべきです。 これはテキスト内のリンクを正しく扱います。

func ToHTML

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

ToHTMLはコメントテキストをフォーマットされたHTMLに変換します。

Deprecated: ToHTMLはドキュメントリンクを識別できません ドキュメントコメント内のリンクは、テキストがパッケージから取得された内容を知っている必要があるため、このAPIには含まれていません。

*doc.Package pがテキストが見つかった場所で見つかる場合、 ToHTML(w, text, nil)は以下のように置き換えられます：

w.Write(p.HTML(text))

これは次の省略形です：

w.Write(p.Printer().HTML(p.Parser().Parse(text)))

wordsがnilでない場合、より長い置換は次のとおりです：

parser := p.Parser()
parser.Words = words
w.Write(p.Printer().HTML(parser.Parse(d)))

func ToText

func ToText(w io.Writer, text string, prefix, codePrefix string, width int)

ToTextはコメントテキストを整形されたテキストに変換します。

Deprecated: ToTextはドキュメントリンクを識別できません。 ドキュメントリンクはテキストが含まれるパッケージを知る必要があるため、 このAPIには含まれていません。

*doc.Package pでテキストが見つかった場合、 ToText(w, text, "", "\t", 80)は次のように置き換えられます:

w.Write(p.Text(text))

一般的な場合、ToText(w, text, prefix, codePrefix, width)は次のように置き換えられます:

d := p.Parser().Parse(text)
pr := p.Printer()
pr.TextPrefix = prefix
pr.TextCodePrefix = codePrefix
pr.TextWidth = width
w.Write(pr.Text(d))

詳細については、Package.Text と comment.Printer.Text のドキュメントを参照してください。

Types

type Example

type Example struct {
	Name        string
	Suffix      string
	Doc         string
	Code        ast.Node
	Play        *ast.File
	Comments    []*ast.CommentGroup
	Output      string
	Unordered   bool
	EmptyOutput bool
	Order       int
}

Example はテストソースファイル内で見つかった関数の例を表します。

func Examples

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

ExamplesはtestFilesで見つかった例を、Nameフィールドでソートして返します。 Orderフィールドには、例が出現した順序が記録されます。 Suffixフィールドは、Examplesが直接呼び出された場合は値が入りませんが、 NewFromFilesによってtest.goファイルで見つかった例にのみ値が入ります。

プレイ可能な例は、名前が"_test"で終わるパッケージにある必要があります。 例は、次のいずれかの場合に「プレイ可能」です（Playフィールドが非nilである場合）：

• 例の関数が自己完結している場合：関数は他のパッケージの識別子（または"int"などの予め宣言された識別子）のみを参照し、テストファイルにドットインポートが含まれていない。
• テストファイル全体が例である場合：ファイルには正確に1つの例関数、テスト、fuzzテスト、またはベンチマーク関数が含まれ、例関数以外の少なくとも1つのトップレベル関数、型、変数、または定数宣言が存在する。

type Filter

type Filter func(string) bool

type Func

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

	// メソッド
	// (関数の場合、これらのフィールドはそれぞれのゼロ値を持ちます)
	Recv  string
	Orig  string
	Level int

	// Examplesはこの関数またはメソッドに関連付けられた並べ替えられた例のリストです。例は、NewFromFilesに提供される_test.goファイルから抽出されます。
	Examples []*Example
}

Funcはfunc宣言のためのドキュメンテーションです。

type Mode

type Mode int

Modeの値は、NewとNewFromFilesの動作を制御します。

const (

	// AllDeclsは、公開されているものだけでなく、すべてのパッケージレベルの宣言のドキュメントを抽出するよう指示します。
	AllDecls Mode = 1 << iota

	// AllMethodsは、見えない（非公開）無名フィールドのみでなく、すべての埋め込まれたメソッドを表示するように指定します。
	AllMethods

	// PreserveASTは、ASTを変更せずにそのまま保持することを指定します。もともと、godocでは、関数の本体などのASTの一部がnilになってメモリを節約していましたが、すべてのプログラムがその動作を望むわけではありません。
	PreserveAST
)

type Note

type Note struct {
	Pos, End token.Pos
	UID      string
	Body     string
}

Noteは"MARKER（uid）：ノートの本文"で始まるマークされたコメントを表します。 マーカーが2つ以上の大文字[A-Z]とuidが少なくとも1つの文字で構成されるノートは認識されます。 uidの後ろの":"はオプションです。 ノートはPackage.Notesマップに、ノートのマーカーをインデックスとして収集されます。

type 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

	// Examplesはパッケージに関連付けられた例のソートされたリストです。
	// これらの例はNewFromFilesに提供される_test.goファイルから抽出されます。
	Examples []*Example
	// contains filtered or unexported fields
}

Packageはパッケージ全体のドキュメントです。

func New

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

Newは指定されたパッケージASTのパッケージドキュメントを計算します。 NewはAST pkgを所有し、編集または上書きすることができます。 Examplesフィールドが入力されている場合は、NewFromFilesを使用して パッケージの_test.goファイルを含めてください。

func NewFromFiles

func NewFromFiles(fset *token.FileSet, files []*ast.File, importPath string, opts ...any) (*Package, error)

NewFromFilesはパッケージのドキュメントを計算します。

パッケージは*ast.Filesのリストと対応するファイルセットで指定されます。 ファイルセットはnilであってはなりません。 NewFromFilesはドキュメントを計算する際に提供されたすべてのファイルを使用しますので、 呼び出し側は必要なビルドコンテキストに一致するファイルのみを提供する責任があります。 ファイルがビルドコンテキストに一致するかどうかを判断するためには、 "go/build".Context.MatchFileを使用できます。 この関数は、望ましいGOOSおよびGOARCHの値と他のビルド制約と一致するかどうかを判断します。 パッケージのインポートパスはimportPathで指定されます。

_test.goファイルに見つかった例は、それらの名前に基づいて対応する型、関数、メソッド、またはパッケージに関連付けられます。 もし例の名前に接尾辞がある場合、それはExample.Suffixフィールドに設定されます。 名前が正しくない例はスキップされます。

オプションとして、抽出の振る舞いの低レベルな側面を制御するためにMode型の単一の追加引数を指定することができます。

NewFromFilesはASTファイルの所有権を持ち、それらを編集する場合があります。 ただし、PreserveASTモードビットがオンになっている場合は、編集しません。

Example

この例は、NewFromFilesを使用してパッケージのドキュメントと例を計算する方法を示しています。

// srcとtestは、ドキュメントが計算されるパッケージを構成する2つのソースファイルです。
const src = `
// This is the package comment.
package p

import "fmt"

// This comment is associated with the Greet function.
func Greet(who string) {
	fmt.Printf("Hello, %s!\n", who)
}
`
const test = `
package p_test

// This comment is associated with the ExampleGreet_world example.
func ExampleGreet_world() {
	Greet("world")
}
`

// srcとtestを解析してASTを作成します。
fset := token.NewFileSet()
files := []*ast.File{
	mustParse(fset, "src.go", src),
	mustParse(fset, "src_test.go", test),
}

// 例を用いて計算パッケージのドキュメントを作成します。
p, err := doc.NewFromFiles(fset, files, "example.com/p")
if err != nil {
	panic(err)
}

fmt.Printf("package %s - %s", p.Name, p.Doc)
fmt.Printf("func %s - %s", p.Funcs[0].Name, p.Funcs[0].Doc)
fmt.Printf(" ⤷ example with suffix %q - %s", p.Funcs[0].Examples[0].Suffix, p.Funcs[0].Examples[0].Doc)

Output:

package p - This is the package comment.
func Greet - This comment is associated with the Greet function.
 ⤷ example with suffix "world" - This comment is associated with the ExampleGreet_world example.

func (*Package) Filter

func (p *Package) Filter(f Filter)

Filterは、フィルターfを通過しない名前のドキュメントを除外します。 TODO（gri）："Type.Method"を名前として認識する。

func (*Package) HTML

func (p *Package) HTML(text string) []byte

HTMLは、ドキュメントコメントテキストのフォーマットされたHTMLを返します。

HTMLの詳細をカスタマイズするには、[Package.Printer]を使用して[comment.Printer]を取得し、そのHTMLメソッドを呼び出す前に設定します。

func (*Package) Markdown

func (p *Package) Markdown(text string) []byte

MarkdownはドキュメントコメントテキストのフォーマットされたMarkdownを返します。

Markdownの詳細をカスタマイズするには、[Package.Printer]を使用して[comment.Printer]を取得し、 そのMarkdownメソッドを呼び出す前に設定してください。

func (*Package) Parser

func (p *Package) Parser() *comment.Parser

Parserは、パッケージpからドキュメントコメントを解析するために設定されたドキュメントコメントパーサーを返します。 各呼び出しは新しいパーサーを返すため、呼び出し元は使用前にカスタマイズすることができます。

func (*Package) Printer

func (p *Package) Printer() *comment.Printer

Printerは、パッケージpからドキュメントコメントの印刷に設定されたドキュメントコメントプリンターを返します。 各呼び出しは、新しいプリンターを返すため、呼び出し元は使用前にカスタマイズすることができます。

func (*Package) Synopsis

func (p *Package) Synopsis(text string) string

Synopsisは、テキスト内の最初の文のクリーニングされたバージョンを返します。 その文は、最初のピリオドの後に空白が続き、正確に1つの大文字で始まっていない、または最初の段落区切りの直前に終わります。 結果の文字列には、\n、\r、または\tの文字がなく、単語間には単一のスペースのみが使用されます。 テキストがIllegalPrefixesのいずれかで始まる場合、結果は空の文字列です。

func (*Package) Text

func (p *Package) Text(text string) []byte

Textは、ドキュメントコメントのテキストを80のユニコードコードポイントに折り返し、コードブロックのインデントにはタブを使用したフォーマット済みのテキストを返します。

フォーマットの詳細をカスタマイズするには、[Package.Printer]を使用して[comment.Printer]を取得し、そのTextメソッドを呼び出す前に設定してください。

type Type

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

	// 関連する宣言
	Consts  []*Value
	Vars    []*Value
	Funcs   []*Func
	Methods []*Func

	// Examplesは、この型に関連付けられた例のソートされたリストです。例は、NewFromFilesに提供される_test.goファイルから抽出されます。
	Examples []*Example
}

Typeは型宣言のためのドキュメントです。

type Value

type Value struct {
	Doc   string
	Names []string
	Decl  *ast.GenDecl
	// contains filtered or unexported fields
}

Valueは（おそらくグループ化された）varまたはconstの宣言のためのドキュメントです。