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

• 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 s)
  

  Synopsis returns a cleaned version of the first sentence in s.
  That sentence ends after the first period followed by space and
  not preceded by exactly one uppercase letter. The result string
  has no \n, \r, or \t characters and uses only single spaces between
  words. If s starts with any of the IllegalPrefixes, the result
  is the empty string.
  
  Go input arguments: (s string)
  
  Go returns: string
  
  Joker input arguments: [^String s]
  
  Joker returns: ^String

• ToText

  Function v1.0

  (ToText w text indent preIndent width)
  

  ToText prepares comment text for presentation in textual output.
  It wraps paragraphs of text to width or fewer Unicode code points
  and then prefixes each line with the indent. In preformatted sections
  (such as program text), it prefixes each non-blank line with preIndent.
  
  A pair of (consecutive) backticks (`) is converted to a unicode left quote (“), and a pair of (consecutive)
  single quotes (') is converted to a unicode right quote (”).
  
  Go input arguments: (w io.Writer, text string, indent string, preIndent string, width int)
  
  Joker input arguments: [^go.std.io/Writer w, ^String text, ^String indent, ^String preIndent, ^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.
  

• *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.