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

/// DefaultLookupPackage is the default package lookup
/// function, used when [Parser.LookupPackage] is nil.
/// It recognizes names of the packages from the standard
/// library with single-element import paths, such as math,
/// which would otherwise be impossible to name.
/// 
/// Note that the go/doc package provides a more sophisticated
/// lookup based on the imports used in the current package.
pub fn DefaultLookupPackage(name: string) -> Option<string>

/// A Block is block-level content in a doc comment,
/// one of [*Code], [*Heading], [*List], or [*Paragraph].
pub interface Block {}

/// A Code is a preformatted code block.
pub struct Code {
  pub Text: string,
}

/// A Doc is a parsed Go doc comment.
pub struct Doc {
  pub Content: Slice<Option<Block>>,
  pub Links: Slice<Option<Ref<LinkDef>>>,
}

/// A DocLink is a link to documentation for a Go package or symbol.
pub struct DocLink {
  pub Text: Slice<Option<Text>>,
  pub ImportPath: string,
  pub Recv: string,
  pub Name: string,
}

/// A Heading is a doc comment heading.
pub struct Heading {
  pub Text: Slice<Option<Text>>,
}

/// An Italic is a string rendered as italicized text.
pub struct Italic(string)

/// A Link is a link to a specific URL.
pub struct Link {
  pub Auto: bool,
  pub Text: Slice<Option<Text>>,
  pub URL: string,
}

/// A LinkDef is a single link definition.
pub struct LinkDef {
  pub Text: string,
  pub URL: string,
  pub Used: bool,
}

/// A List is a numbered or bullet list.
/// Lists are always non-empty: len(Items) > 0.
/// In a numbered list, every Items[i].Number is a non-empty string.
/// In a bullet list, every Items[i].Number is an empty string.
pub struct List {
  pub Items: Slice<Option<Ref<ListItem>>>,
  pub ForceBlankBefore: bool,
  pub ForceBlankBetween: bool,
}

/// A ListItem is a single item in a numbered or bullet list.
pub struct ListItem {
  pub Number: string,
  pub Content: Slice<Option<Block>>,
}

/// A Paragraph is a paragraph of text.
pub struct Paragraph {
  pub Text: Slice<Option<Text>>,
}

/// A Parser is a doc comment parser.
/// The fields in the struct can be filled in before calling [Parser.Parse]
/// in order to customize the details of the parsing process.
pub struct Parser {
  pub Words: Map<string, string>,
  pub LookupPackage: Option<fn(string) -> Option<string>>,
  pub LookupSym: Option<fn(string, string) -> bool>,
}

/// A Plain is a string rendered as plain text (not italicized).
pub struct Plain(string)

/// A Printer is a doc comment printer.
/// The fields in the struct can be filled in before calling
/// any of the printing methods
/// in order to customize the details of the printing process.
pub struct Printer {
  pub HeadingLevel: int,
  pub HeadingID: Option<fn(Ref<Heading>) -> string>,
  pub DocLinkURL: Option<fn(Ref<DocLink>) -> string>,
  pub DocLinkBaseURL: string,
  pub TextPrefix: string,
  pub TextCodePrefix: string,
  pub TextWidth: int,
}

/// A Text is text-level content in a doc comment,
/// one of [Plain], [Italic], [*Link], or [*DocLink].
pub interface Text {}

impl DocLink {
  /// DefaultURL constructs and returns the documentation URL for l,
  /// using baseURL as a prefix for links to other packages.
  /// 
  /// The possible forms returned by DefaultURL are:
  ///   - baseURL/ImportPath, for a link to another package
  ///   - baseURL/ImportPath#Name, for a link to a const, func, type, or var in another package
  ///   - baseURL/ImportPath#Recv.Name, for a link to a method in another package
  ///   - #Name, for a link to a const, func, type, or var in this package
  ///   - #Recv.Name, for a link to a method in this package
  /// 
  /// If baseURL ends in a trailing slash, then DefaultURL inserts
  /// a slash between ImportPath and # in the anchored forms.
  /// For example, here are some baseURL values and URLs they can generate:
  /// 
  /// 	"/pkg/" → "/pkg/math/#Sqrt"
  /// 	"/pkg"  → "/pkg/math#Sqrt"
  /// 	"/"     → "/math/#Sqrt"
  /// 	""      → "/math#Sqrt"
  fn DefaultURL(self: Ref<DocLink>, baseURL: string) -> string
}

impl Heading {
  /// DefaultID returns the default anchor ID for the heading h.
  /// 
  /// The default anchor ID is constructed by converting every
  /// rune that is not alphanumeric ASCII to an underscore
  /// and then adding the prefix “hdr-”.
  /// For example, if the heading text is “Go Doc Comments”,
  /// the default ID is “hdr-Go_Doc_Comments”.
  fn DefaultID(self: Ref<Heading>) -> string
}

impl List {
  /// BlankBefore reports whether a reformatting of the comment
  /// should include a blank line before the list.
  /// The default rule is the same as for [BlankBetween]:
  /// if the list item content contains any blank lines
  /// (meaning at least one item has multiple paragraphs)
  /// then the list itself must be preceded by a blank line.
  /// A preceding blank line can be forced by setting [List].ForceBlankBefore.
  fn BlankBefore(self: Ref<List>) -> bool

  /// BlankBetween reports whether a reformatting of the comment
  /// should include a blank line between each pair of list items.
  /// The default rule is that if the list item content contains any blank lines
  /// (meaning at least one item has multiple paragraphs)
  /// then list items must themselves be separated by blank lines.
  /// Blank line separators can be forced by setting [List].ForceBlankBetween.
  fn BlankBetween(self: Ref<List>) -> bool
}

impl Parser {
  /// Parse parses the doc comment text and returns the *[Doc] form.
  /// Comment markers (/* // and */) in the text must have already been removed.
  fn Parse(self: Ref<Parser>, text: string) -> Ref<Doc>
}

impl Printer {
  /// Comment returns the standard Go formatting of the [Doc],
  /// without any comment markers.
  fn Comment(self: Ref<Printer>, d: Ref<Doc>) -> Slice<uint8>

  /// HTML returns an HTML formatting of the [Doc].
  /// See the [Printer] documentation for ways to customize the HTML output.
  fn HTML(self: Ref<Printer>, d: Ref<Doc>) -> Slice<uint8>

  /// Markdown returns a Markdown formatting of the Doc.
  /// See the [Printer] documentation for ways to customize the Markdown output.
  fn Markdown(self: Ref<Printer>, d: Ref<Doc>) -> Slice<uint8>

  /// Text returns a textual formatting of the [Doc].
  /// See the [Printer] documentation for ways to customize the text output.
  fn Text(self: Ref<Printer>, d: Ref<Doc>) -> Slice<uint8>
}
