Closed
Description
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
orExample_suffix
) - A function (e.g.,
ExampleF
orExampleF_suffix
) - A type (e.g.,
ExampleT
orExampleT_suffix
) - A method (e.g.,
ExampleT_M
orExampleT_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 theast.Package.Files
input to produce an internal[]Example
.- An
Examples []Example
field is added to thePackage
,Type
, andFunc
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