// Generated by Lisette bindgen
// Source: go/doc (Go stdlib)
// Go: 1.25.5
// Lisette: 0.1.20

import "go:go/ast"
import "go:go/doc/comment"
import "go:go/token"
import "go:io"

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

pub fn New(pkg: Ref<ast.Package>, importPath: string, mode: Mode) -> Ref<Package>

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].
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<uint8>

  /// 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<uint8>

  /// 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<uint8>
}
