# Packages
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]のドキュメントを参照してください。
*/.
# Functions
ExamplesはtestFilesで見つかった例を、Nameフィールドでソートして返します。 Orderフィールドには、例が出現した順序が記録されます。 Suffixフィールドは、Examplesが直接呼び出された場合は値が入りませんが、 [NewFromFiles] によってtest.goファイルで見つかった例にのみ値が入ります。
プレイ可能な例は、名前が"_test"で終わるパッケージにある必要があります。 例は、次のいずれかの場合に「プレイ可能」です(Playフィールドが非nilである場合): - 例の関数が自己完結している場合:関数は他のパッケージの識別子(または"int"などの予め宣言された識別子)のみを参照し、テストファイルにドットインポートが含まれていない。 - テストファイル全体が例である場合:ファイルには正確に1つの例関数、テスト、fuzzテスト、またはベンチマーク関数が含まれ、例関数以外の少なくとも1つのトップレベル関数、型、変数、または定数宣言が存在する。.
IsPredeclaredは、sが事前に宣言された識別子であるかどうかを報告します。.
Newは指定されたパッケージASTのパッケージドキュメントを計算します。 NewはAST pkgを所有し、編集または上書きすることができます。 [Examples] フィールドが入力されている場合は、[NewFromFiles] を使用して パッケージの_test.goファイルを含めてください。.
NewFromFilesはパッケージのドキュメントを計算します。
パッケージは*ast.Filesのリストと対応するファイルセットで指定されます。 ファイルセットはnilであってはなりません。 NewFromFilesはドキュメントを計算する際に提供されたすべてのファイルを使用しますので、 呼び出し側は必要なビルドコンテキストに一致するファイルのみを提供する責任があります。 ファイルがビルドコンテキストに一致するかどうかを判断するためには、 "go/build".Context.MatchFileを使用できます。 この関数は、望ましいGOOSおよびGOARCHの値と他のビルド制約と一致するかどうかを判断します。 パッケージのインポートパスはimportPathで指定されます。
_test.goファイルに見つかった例は、それらの名前に基づいて対応する型、関数、メソッド、またはパッケージに関連付けられます。 もし例の名前に接尾辞がある場合、それは [Example.Suffix] フィールドに設定されます。 名前が正しくない [Example] はスキップされます。
オプションとして、抽出の振る舞いの低レベルな側面を制御するために [Mode] 型の単一の追加引数を指定することができます。
NewFromFilesはASTファイルの所有権を持ち、それらを編集する場合があります。 ただし、PreserveASTモードビットがオンになっている場合は、編集しません。.
Synopsisはtextの最初の文のクリーニングされたバージョンを返します。
Deprecated: 新しいプログラムは代わりに[Package.Synopsis]を使用するべきです。 これはテキスト内のリンクを正しく扱います。.
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))).
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] のドキュメントを参照してください。.
# Constants
AllDeclsは、公開されているものだけでなく、すべてのパッケージレベルの宣言のドキュメントを抽出するよう指示します。.
AllMethodsは、見えない(非公開)無名フィールドのみでなく、すべての埋め込まれたメソッドを表示するように指定します。.
PreserveASTは、ASTを変更せずにそのまま保持することを指定します。もともと、godocでは、関数の本体などのASTの一部がnilになってメモリを節約していましたが、すべてのプログラムがその動作を望むわけではありません。.
# Variables
IllegalPrefixesは、ドキュメントコメントではないコメントを識別するための小文字の接頭辞のリストです。 これにより、パッケージ文の直前にある著作権表示のよくある間違いをドキュメントコメントと誤解しないようにします。.
# Structs
Example はテストソースファイル内で見つかった関数の例を表します。.
Funcはfunc宣言のためのドキュメンテーションです。.
Noteは"MARKER(uid):ノートの本文"で始まるマークされたコメントを表します。 マーカーが2つ以上の大文字[A-Z]とuidが少なくとも1つの文字で構成されるノートは認識されます。 uidの後ろの":"はオプションです。 ノートはPackage.Notesマップに、ノートのマーカーをインデックスとして収集されます。.
Packageはパッケージ全体のドキュメントです。.
Typeは型宣言のためのドキュメントです。.
Valueは(おそらくグループ化された)varまたはconstの宣言のためのドキュメントです。.