// Generated by Lisette bindgen
// Source: go/doc (Go stdlib)
// Go: 1.25.10
// Lisette: 0.2.1
import "go:go/ast"
import "go:go/doc/comment"
import "go:go/token"
import "go:io"
/// Examples returns the examples found in testFiles, sorted by Name field.
/// The Order fields record the order in which the examples were encountered.
/// The Suffix field is not populated when Examples is called directly, it is
/// only populated by [NewFromFiles] for examples it finds in _test.go files.
///
/// Playable Examples must be in a package whose name ends in "_test".
/// An Example is "playable" (the Play field is non-nil) in either of these
/// circumstances:
/// - The example function is self-contained: the function references only
/// identifiers from other packages (or predeclared identifiers, such as
/// "int") and the test file does not include a dot import.
/// - The entire test file is the example: the file contains exactly one
/// example function, zero test, fuzz test, or benchmark function, and at
/// least one top-level function, type, variable, or constant declaration
/// other than the example function.
pub fn Examples(testFiles: VarArgs<Ref<ast.File>>) -> Slice<Ref<Example>>
/// IsPredeclared reports whether s is a predeclared identifier.
pub fn IsPredeclared(s: string) -> bool
/// New computes the package documentation for the given package AST.
/// New takes ownership of the AST pkg and may edit or overwrite it.
/// To have the [Examples] fields populated, use [NewFromFiles] and include
/// the package's _test.go files.
pub fn New(pkg: Ref<ast.Package>, importPath: string, mode: Mode) -> Ref<Package>
/// NewFromFiles computes documentation for a package.
///
/// The package is specified by a list of *ast.Files and corresponding
/// file set, which must not be nil.
///
/// NewFromFiles uses all provided files when computing documentation,
/// so it is the caller's responsibility to provide only the files that
/// match the desired build context. "go/build".Context.MatchFile can
/// be used for determining whether a file matches a build context with
/// the desired GOOS and GOARCH values, and other build constraints.
/// The import path of the package is specified by importPath.
///
/// Examples found in _test.go files are associated with the corresponding
/// type, function, method, or the package, based on their name.
/// If the example has a suffix in its name, it is set in the
/// [Example.Suffix] field. [Examples] with malformed names are skipped.
///
/// Optionally, a single extra argument of type [Mode] can be provided to
/// control low-level aspects of the documentation extraction behavior.
///
/// NewFromFiles takes ownership of the AST files and may edit them,
/// unless the PreserveAST Mode bit is on.
pub fn NewFromFiles(
fset: Ref<token.FileSet>,
files: Slice<Ref<ast.File>>,
importPath: string,
opts: VarArgs<Unknown>,
) -> Result<Ref<Package>, error>
/// Synopsis returns a cleaned version of the first sentence in text.
///
/// Deprecated: New programs should use [Package.Synopsis] instead,
/// which handles links in text properly.
pub fn Synopsis(text: string) -> string
/// ToHTML converts comment text to formatted HTML.
///
/// Deprecated: ToHTML cannot identify documentation links
/// in the doc comment, because they depend on knowing what
/// package the text came from, which is not included in this API.
///
/// Given the *[doc.Package] p where text was found,
/// ToHTML(w, text, nil) can be replaced by:
///
/// w.Write(p.HTML(text))
///
/// which is in turn shorthand for:
///
/// w.Write(p.Printer().HTML(p.Parser().Parse(text)))
///
/// If words may be non-nil, the longer replacement is:
///
/// parser := p.Parser()
/// parser.Words = words
/// w.Write(p.Printer().HTML(parser.Parse(d)))
pub fn ToHTML(w: io.Writer, text: string, words: Map<string, string>)
/// ToText converts comment text to formatted text.
///
/// Deprecated: ToText cannot identify documentation links
/// in the doc comment, because they depend on knowing what
/// package the text came from, which is not included in this API.
///
/// Given the *[doc.Package] p where text was found,
/// ToText(w, text, "", "\t", 80) can be replaced by:
///
/// w.Write(p.Text(text))
///
/// In the general case, ToText(w, text, prefix, codePrefix, width)
/// can be replaced by:
///
/// d := p.Parser().Parse(text)
/// pr := p.Printer()
/// pr.TextPrefix = prefix
/// pr.TextCodePrefix = codePrefix
/// pr.TextWidth = width
/// w.Write(pr.Text(d))
///
/// See the documentation for [Package.Text] and [comment.Printer.Text]
/// for more details.
pub fn ToText(
w: io.Writer,
text: string,
prefix: string,
codePrefix: string,
width: int,
)
/// An Example represents an example function found in a test source file.
pub struct Example {
pub Name: string,
pub Suffix: string,
pub Doc: string,
pub Code: Option<ast.Node>,
pub Play: Option<Ref<ast.File>>,
pub Comments: Slice<Option<Ref<ast.CommentGroup>>>,
pub Output: string,
pub Unordered: bool,
pub EmptyOutput: bool,
pub Order: int,
}
pub type Filter = fn(string) -> bool
/// Func is the documentation for a func declaration.
pub struct Func {
pub Doc: string,
pub Name: string,
pub Decl: Option<Ref<ast.FuncDecl>>,
pub Recv: string,
pub Orig: string,
pub Level: int,
pub Examples: Slice<Option<Ref<Example>>>,
}
/// Mode values control the operation of [New] and [NewFromFiles].
#[go(bit_flag_set)]
pub struct Mode(int)
/// A Note represents a marked comment starting with "MARKER(uid): note body".
/// Any note with a marker of 2 or more upper case [A-Z] letters and a uid of
/// at least one character is recognized. The ":" following the uid is optional.
/// Notes are collected in the Package.Notes map indexed by the notes marker.
pub struct Note {
pub Pos: token.Pos,
pub End: token.Pos,
pub UID: string,
pub Body: string,
}
/// Package is the documentation for an entire package.
pub struct Package {
pub Doc: string,
pub Name: string,
pub ImportPath: string,
pub Imports: Slice<string>,
pub Filenames: Slice<string>,
pub Notes: Map<string, Slice<Option<Ref<Note>>>>,
pub Bugs: Slice<string>,
pub Consts: Slice<Option<Ref<Value>>>,
pub Types: Slice<Option<Ref<Type>>>,
pub Vars: Slice<Option<Ref<Value>>>,
pub Funcs: Slice<Option<Ref<Func>>>,
pub Examples: Slice<Option<Ref<Example>>>,
}
/// Type is the documentation for a type declaration.
pub struct Type {
pub Doc: string,
pub Name: string,
pub Decl: Option<Ref<ast.GenDecl>>,
pub Consts: Slice<Option<Ref<Value>>>,
pub Vars: Slice<Option<Ref<Value>>>,
pub Funcs: Slice<Option<Ref<Func>>>,
pub Methods: Slice<Option<Ref<Func>>>,
pub Examples: Slice<Option<Ref<Example>>>,
}
/// Value is the documentation for a (possibly grouped) var or const declaration.
pub struct Value {
pub Doc: string,
pub Names: Slice<string>,
pub Decl: Option<Ref<ast.GenDecl>>,
}
pub const AllDecls: Mode = 1
pub const AllMethods: Mode = 2
pub const PreserveAST: Mode = 4
/// IllegalPrefixes is a list of lower-case prefixes that identify
/// a comment as not being a doc comment.
/// This helps to avoid misinterpreting the common mistake
/// of a copyright notice immediately before a package statement
/// as being a doc comment.
pub var IllegalPrefixes: Slice<string>
impl Package {
/// Filter eliminates documentation for names that don't pass through the filter f.
/// TODO(gri): Recognize "Type.Method" as a name.
fn Filter(self: Ref<Package>, f: Filter)
/// HTML returns formatted HTML for the doc comment text.
///
/// To customize details of the HTML, use [Package.Printer]
/// to obtain a [comment.Printer], and configure it
/// before calling its HTML method.
fn HTML(self: Ref<Package>, text: string) -> Slice<byte>
/// Markdown returns formatted Markdown for the doc comment text.
///
/// To customize details of the Markdown, use [Package.Printer]
/// to obtain a [comment.Printer], and configure it
/// before calling its Markdown method.
fn Markdown(self: Ref<Package>, text: string) -> Slice<byte>
/// Parser returns a doc comment parser configured
/// for parsing doc comments from package p.
/// Each call returns a new parser, so that the caller may
/// customize it before use.
fn Parser(self: Ref<Package>) -> Ref<comment.Parser>
/// Printer returns a doc comment printer configured
/// for printing doc comments from package p.
/// Each call returns a new printer, so that the caller may
/// customize it before use.
fn Printer(self: Ref<Package>) -> Ref<comment.Printer>
/// Synopsis returns a cleaned version of the first sentence in text.
/// That sentence ends after the first period followed by space and not
/// preceded by exactly one uppercase letter, or at the first paragraph break.
/// The result string has no \n, \r, or \t characters and uses only single
/// spaces between words. If text starts with any of the [IllegalPrefixes],
/// the result is the empty string.
fn Synopsis(self: Ref<Package>, text: string) -> string
/// Text returns formatted text for the doc comment text,
/// wrapped to 80 Unicode code points and using tabs for
/// code block indentation.
///
/// To customize details of the formatting, use [Package.Printer]
/// to obtain a [comment.Printer], and configure it
/// before calling its Text method.
fn Text(self: Ref<Package>, text: string) -> Slice<byte>
}