Documentation
¶
Overview ¶
commentパッケージは、Goのドキュメントコメント（ドキュメンテーションコメント）を解析および再フォーマットするためのものです。 パッケージ、const、func、type、またはvarのトップレベルの宣言の直前にあるコメントを指します。
Goのドキュメントコメントの構文は、リンク、見出し、段落、リスト（ネストなし）、および整形済みのテキストブロックをサポートする、 Markdownの簡略化されたサブセットです。構文の詳細は、https://go.dev/doc/commentで文書化されています。
（コメントマーカーを削除した後の）ドキュメントコメントに関連付けられたテキストを解析するには、[Parser]を使用します：
var p comment.Parser doc := p.Parse(text)
結果は、[*Doc]です。 ドキュメントコメント、HTML、Markdown、またはプレーンテキストとして再フォーマットするには、[Printer]を使用します：
var pr comment.Printer os.Stdout.Write(pr.Text(doc))
[Parser]と[Printer]の型は、その操作をカスタマイズするために変更できる構造体です。 詳細については、それらの型のドキュメントを参照してください。
再フォーマットに追加の制御が必要な使用例では、解析された構文自体を検査することで独自のロジックを実装できます。 概要および追加の型へのリンクについては、Doc、Block、[Text]のドキュメントを参照してください。
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultLookupPackage ¶
DefaultLookupPackageは、[Parser.LookupPackage] がnilの場合に使用されるデフォルトのパッケージルックアップ関数です。 これは、単一要素のインポートパスを持つ標準ライブラリのパッケージ名を認識します。 それ以外の場合は、名前を付けることができません。
ただし、現在のパッケージで使用されているインポートに基づいたより洗練されたルックアップを提供するgo/docパッケージがあることに注意してください。
Types ¶
type Block ¶
type Block interface {
// contains filtered or unexported methods
}
ブロックは、ドキュメントコメント内のブロックレベルのコンテンツであり、*Code、*Heading、*List、または[*Paragraph]のいずれかです。
type Code ¶
type Code struct {
// Textは事前に書式設定されたテキストで、改行文字で終わります。
// 複数行になることがあり、それぞれの行は改行文字で終わります。
// 空でなく、空白行で始まることも終わることもありません。
Text string
}
Code は、整形済みのコードブロックです。
type Doc ¶
type Doc struct {
// Contentはコメント内のコンテンツブロックのシーケンスです。
Content []Block
// Linksはコメント内のリンクの定義です。
Links []*LinkDef
}
Docは解析されたGoドキュメントコメントです。
type DocLink ¶
type DocLink struct {
Text []Text
// ImportPath、Recv、Nameは、Goのパッケージまたはシンボルを識別します。
// 非空のフィールドの組み合わせは以下の通りです：
// - ImportPath：別のパッケージへのリンク
// - ImportPath、Name：別のパッケージ内のconst、func、type、varへのリンク
// - ImportPath、Recv、Name：別のパッケージ内のメソッドへのリンク
// - Name：このパッケージ内のconst、func、type、varへのリンク
// - Recv、Name：このパッケージ内のメソッドへのリンク
ImportPath string
Recv string
Name string
}
DocLinkはGoのパッケージまたはシンボルのドキュメントへのリンクです。
func (*DocLink) DefaultURL ¶
DefaultURLは、baseURLをプレフィックスとして他のパッケージへのリンクのためにlのドキュメンテーションURLを構築して返します。
DefaultURLが返す可能性のある形式は以下の通りです：
- baseURL/ImportPath、他のパッケージへのリンク
- baseURL/ImportPath#Name、他のパッケージのconst、func、type、またはvarへのリンク
- baseURL/ImportPath#Recv.Name、他のパッケージのメソッドへのリンク
- #Name、このパッケージのconst、func、type、またはvarへのリンク
- #Recv.Name、このパッケージのメソッドへのリンク
baseURLが末尾にスラッシュで終わる場合、アンカー形式のImportPathと#の間にスラッシュが挿入されます。 例えば、以下はいくつかのbaseURL値とそれらが生成するURLの例です：
"/pkg/" → "/pkg/math/#Sqrt" "/pkg" → "/pkg/math#Sqrt" "/" → "/math/#Sqrt" "" → "/math#Sqrt"
type List ¶
type List struct {
// Itemsはアイテムのリストです。
Items []*ListItem
// ForceBlankBeforeは、コメントの再フォーマット時に、
// 通常の条件を無視してリストの前に空行が必要であることを示します。
// BlankBeforeメソッドを参照してください。
//
// コメントパーサーは、リストの前に空行がある場合に
// ForceBlankBeforeを設定し、空行が出力時に保持されるようにします。
ForceBlankBefore bool
// ForceBlankBetweenは、コメントを再フォーマットする際、リストの項目は必ず空白行で区切られる必要があることを示しています。通常の条件を上書きします。BlankBetweenメソッドを参照してください。
//
// コメントパーサーは、リスト内の任意の二つの項目の間に空白行がある場合、それをプリントする際に空白行が保持されることを確認するために、ForceBlankBetweenを設定します。
ForceBlankBetween bool
}
リストは番号付きまたは箇条書きリストです。 リストは常に空でないことが保証されます：len(Items) > 0。 番号付きのリストでは、Items[i].Numberは空ではない文字列です。 箇条書きリストでは、Items[i].Numberは空の文字列です。
func (*List) BlankBefore ¶
BlankBeforeはコメントのリフォーマットにおいて、リストの前に空行を含めるべきかを報告します。 デフォルトのルールは[BlankBetween]と同じです： もしリストの項目の内容に空行が含まれている場合 （つまり、少なくとも1つの項目に複数の段落がある場合） リスト自体は前に空行を置く必要があります。 先行する空行を強制するためには、List.ForceBlankBeforeを設定することができます。
func (*List) BlankBetween ¶
BlankBetweenはコメントのリフォーマット時に、 リストの項目間に空行を追加する必要があるかどうかを報告します。 デフォルトのルールは、リストの項目の内容に空行が含まれている場合 （つまり、少なくとも1つの項目が複数の段落を持っている場合）、 リストの項目自体も空行で分ける必要があるということです。 空行の区切りは、List.ForceBlankBetweenを設定することで強制することができます。
type ListItem ¶
type ListItem struct {
// Numberは、番号付きリストの10進数の文字列または箇条書きリストの空の文字列です。
Number string
// Contentはリストの内容です。
// 現在、パーサーとプリンターの制限により、Contentの各要素は*Paragraphである必要があります。
Content []Block
}
ListItemは、番号付きまたは点付きリスト内の単一の項目です。
type Parser ¶
type Parser struct {
// WordsはGo言語の識別子に対応する単語のマップであり、斜体にする必要があり、
// かつ可能であればリンクも作成します。
// もしWords[w]が空の文字列であれば、単語wは斜体にのみなります。
// そうでなければ、Words[w]をリンクターゲットとしてリンクが作成されます。
// Wordsは[go/doc.ToHTML]のwordsパラメータに対応します。
Words map[string]string
// LookupPackageはパッケージ名をインポートパスに変換する。
//
// LookupPackage(name)がok == trueを返す場合、[name]
//（または[name.Sym]または[name.Sym.Method]）
//はimportPathのパッケージドキュメントへのリンクと見なされる。
// 空文字列とtrueを返すことも有効であり、その場合はnameが現在のパッケージを参照していると見なされる。
//
// LookupPackage(name)がok == falseを返す場合、
//[name]（または[name.Sym]または[name.Sym.Method]）
//はドキュメントへのリンクと見なされないが、
// nameが標準ライブラリ内のパッケージの完全な（ただし要素が1つだけの）インポートパスである場合、
//[math]や[io.Reader]のように
//例外として扱われる。 LookupPackageはそれらの名前に対しても呼び出されるため、
//同じパッケージ名の他のパッケージのインポートを参照することができる。
//
// LookupPackageをnilに設定するのは、常に""とfalseを返す関数に設定するのと同じです。
LookupPackage func(name string) (importPath string, ok bool)
// LookupSymは、現在のパッケージにシンボル名またはメソッド名が存在するかどうかを報告します。
//
// LookupSym("", "Name")がtrueを返す場合、[Name]はconst、func、type、またはvarのドキュメントリンクと見なされます。
//
// 同様に、LookupSym("Recv", "Name")がtrueを返す場合、[Recv.Name]はtype RecvのメソッドNameのドキュメントリンクと見なされます。
//
// LookupSymをnilに設定することは、常にfalseを返す関数に設定することと同じです。
LookupSym func(recv, name string) (ok bool)
}
Parserはドキュメントコメントのパーサーです。 構造体のフィールドは、Parser.Parse を呼び出す前に埋めることで、 パースプロセスの詳細をカスタマイズすることができます。
type Printer ¶
type Printer struct {
// HeadingLevelはHTMLとMarkdownの見出しに使用されるネストレベルです。
// HeadingLevelがゼロであれば、デフォルトでレベル3に設定され、<h3>と###が使用されます。
HeadingLevel int
// HeadingIDは、HTMLとMarkdownを生成する際に使用する見出しhの見出しID（アンカータグ）を計算する関数です。HeadingIDが空の文字列を返す場合、見出しIDは省略されます。HeadingIDがnilの場合、h.DefaultIDが使用されます。
HeadingID func(h *Heading) string
// DocLinkURLは、与えられたDocLinkのURLを計算する関数です。
// DocLinkURLがnilの場合、link.DefaultURL（p.DocLinkBaseURL）が使用されます。
DocLinkURL func(link *DocLink) string
// DocLinkBaseURLは、DocLinkURLがnilの場合に使用され、DocLinkのURLを構築するために[DocLink.DefaultURL]に渡されます。
// 詳細については、そのメソッドのドキュメントを参照してください。
DocLinkBaseURL string
// TextPrefixは、Textメソッドを使用してテキスト出力を生成する際に、
// 各行の先頭に表示するプレフィックスです。
TextPrefix string
// TextCodePrefixは、テキスト出力を生成する際に各事前に書式設定された（コードブロック）行の先頭に印刷する接頭辞です。
// （TextPrefixに追加ではなく）。
// TextCodePrefixが空の文字列の場合、TextPrefix +"\t"がデフォルト値となります。
TextCodePrefix string
// TextWidthは生成するテキスト行の最大幅であり、Unicodeのコードポイントで測定されます。
// TextPrefixと改行文字を除いたものです。
// TextWidthがゼロの場合、TextPrefixのコードポイント数を除いた80から始まります。
// TextWidthが負の場合、制限はありません。
TextWidth int
}
Printerはドキュメントコメントのプリンターです。 構造体のフィールドは、印刷の詳細をカスタマイズするために、 印刷メソッドのいずれかを呼び出す前に埋めることができます。
Source Files