Namespace: go.std.go.doc

v1.0

Contents

• Summary
• Index
• Constants
• Variables
• Functions, Macros, and Special Forms
• Types

Summary

Provides a low-level interface to the go/doc package.

Package doc extracts source code documentation from a Go AST.

Index

• *Example
• *Filter
• *Func
• *Mode
• *Note
• *Package
• *Type
• *Value
• AllDecls
• AllMethods
• Example
• Examples
• Filter
• Func
• IllegalPrefixes
• IsPredeclared
• Mode
• New
• NewFromFiles
• Note
• Package
• PreserveAST
• Synopsis
• ToText
• Type
• Value
• arrayOfExample
• arrayOfFilter
• arrayOfFunc
• arrayOfMode
• arrayOfNote
• arrayOfPackage
• arrayOfType
• arrayOfValue

Legend

Constant Variable Function Macro Special form Type GoVar Receiver/Method

Constants

Constants are variables with :const true in their metadata. Joker currently does not recognize them as special; as such, it allows redefining them or their values.

(None.)

Variables

• AllDecls

  GoObject v1.0

  AllDecls says to extract documentation for all package-level
  declarations, not just exported ones.
  

• AllMethods

  GoObject v1.0

  AllMethods says to show all embedded methods, not just the ones of
  invisible (unexported) anonymous fields.
  

• IllegalPrefixes

  Var v1.0

  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.
  

• PreserveAST

  GoObject v1.0

  PreserveAST says to leave the AST unmodified. Originally, pieces of
  the AST such as function bodies were nil-ed out to save memory in
  godoc, but not all programs want that behavior.
  

Functions, Macros, and Special Forms

• Examples

  Function v1.0

  (Examples & testFiles)
  

  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.
  
  Go input arguments: (testFiles ...*go/ast.File)
  
  Go returns: []*Example
  
  Joker input arguments: [& ^go.std.go.ast/*File testFiles]
  
  Joker returns: ^arrayOf*Example

• IsPredeclared

  Function v1.0

  (IsPredeclared s)
  

  IsPredeclared reports whether s is a predeclared identifier.
  
  Go input arguments: (s string)
  
  Go returns: bool
  
  Joker input arguments: [^String s]
  
  Joker returns: ^Boolean

• New

  Function v1.0

  (New pkg importPath mode)
  

  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.
  
  Go input arguments: (pkg *go/ast.Package, importPath string, mode Mode)
  
  Go returns: *Package
  
  Joker input arguments: [^go.std.go.ast/*Package pkg, ^String importPath, ^Mode mode]
  
  Joker returns: ^*Package

• NewFromFiles

  Function v1.0

  (NewFromFiles fset files importPath & opts)
  

  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.
  
  Go input arguments: (fset *go/token.FileSet, files []*go/ast.File, importPath string, opts ...any)
  
  Go returns: (*Package, error)
  
  Joker input arguments: [^go.std.go.token/*FileSet fset, ^go.std.go.ast/arrayOf*File files, ^String importPath, & ^GoObject opts]
  
  Joker returns: [^*Package, ^Error]

• Synopsis

  Function v1.0

  (Synopsis text)
  

  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.
  
  Go input arguments: (text string)
  
  Go returns: string
  
  Joker input arguments: [^String text]
  
  Joker returns: ^String

• ToText

  Function v1.0

  (ToText w text prefix codePrefix width)
  

  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.
  
  Go input arguments: (w io.Writer, text string, prefix string, codePrefix string, width int)
  
  Joker input arguments: [^go.std.io/Writer w, ^String text, ^String prefix, ^String codePrefix, ^Int width]

Types

• *Example

  Concrete Type v1.0

  An Example represents an example function found in a test source file.
  

• *Filter

  Concrete Type v1.0

• *Func

  Concrete Type v1.0

  Func is the documentation for a func declaration.
  

• *Mode

  Concrete Type v1.0

  Mode values control the operation of New and NewFromFiles.
  

• *Note

  Concrete Type v1.0

  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.
  

• *Package

  Concrete Type v1.0

  Package is the documentation for an entire package.
  

• Filter

  Receiver for *Package v1.0

  ([f])
  

  Filter eliminates documentation for names that don't pass through the filter f.
  TODO(gri): Recognize "Type.Method" as a name.
  

• HTML

  Receiver for *Package v1.0

  ([text])
  

  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.
  

• Markdown

  Receiver for *Package v1.0

  ([text])
  

  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.
  

• Parser

  Receiver for *Package v1.0

  ([])
  

  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.
  

• Printer

  Receiver for *Package v1.0

  ([])
  

  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.
  

• Synopsis

  Receiver for *Package v1.0

  ([text])
  

  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.
  

• Text

  Receiver for *Package v1.0

  ([text])
  

  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.
  

• *Type

  Concrete Type v1.0

  Type is the documentation for a type declaration.
  

• *Value

  Concrete Type v1.0

  Value is the documentation for a (possibly grouped) var or const declaration.
  

• Example

  Concrete Type v1.0

  An Example represents an example function found in a test source file.
  

• Filter

  Concrete Type v1.0

• Func

  Concrete Type v1.0

  Func is the documentation for a func declaration.
  

• Mode

  Concrete Type v1.0

  Mode values control the operation of New and NewFromFiles.
  

• Note

  Concrete Type v1.0

  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.
  

• Package

  Concrete Type v1.0

  Package is the documentation for an entire package.
  

• Type

  Concrete Type v1.0

  Type is the documentation for a type declaration.
  

• Value

  Concrete Type v1.0

  Value is the documentation for a (possibly grouped) var or const declaration.
  

• arrayOfExample

  Concrete Type v1.0

  An Example represents an example function found in a test source file.
  

• arrayOfFilter

  Concrete Type v1.0

• arrayOfFunc

  Concrete Type v1.0

  Func is the documentation for a func declaration.
  

• arrayOfMode

  Concrete Type v1.0

  Mode values control the operation of New and NewFromFiles.
  

• arrayOfNote

  Concrete Type v1.0

  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.
  

• arrayOfPackage

  Concrete Type v1.0

  Package is the documentation for an entire package.
  

• arrayOfType

  Concrete Type v1.0

  Type is the documentation for a type declaration.
  

• arrayOfValue

  Concrete Type v1.0

  Value is the documentation for a (possibly grouped) var or const declaration.