Skip to content

go/doc: add fields to Example struct to indicate type/method/suffix #23864

Closed
@dsnet

Description

@dsnet

The doc package currently provides:

func Examples(files ...*ast.File) []*Example

Given a set of source files, this only parses out the examples as a flat list.

However, the testing package documents a syntax of how to associate examples with:

  • A package (e.g., Example or Example_suffix)
  • A function (e.g., ExampleF or ExampleF_suffix)
  • A type (e.g., ExampleT or ExampleT_suffix)
  • A method (e.g., ExampleT_M or ExampleT_M_suffix)

As the number of tools that provide godoc-like functionality increases, the manual logic to parse these example names and associate it with the appropriate top-level declaration is somewhat tedious and easy to get wrong.

Given that this syntax is documented, I propose that the doc package provide first-class support for doing this association. The additional functionality is as follows:

  • New uses the ast.Package.Files input to produce an internal []Example.
  • An Examples []Example field is added to the Package, Type, and Func types. They are populated as appropriate according to what the relevant examples are associated with.
  • Examples that do not follow the example syntax or reference an non-existent declaration could be either ignored or just associated with the entire package.

\cc @griesemer

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions