summaryrefslogtreecommitdiff
path: root/src/go/doc/doc.go
Commit message (Collapse)AuthorAgeFilesLines
* go/doc: recognize methods on generic types as FuncsKeith Randall2022-11-101-2/+6
| | | | | | | | | | | | | | | | | | When writing markdown for godoc, we can reference a method M of a type T as [T.M]. This doesn't currently work for methods on generic types because the declaration of the type parameter gets in the way. (You'd have to write [T[P].M] and that doesn't parse, and even if it did you'd have to spell "P" correctly.) Get rid of the type parameter when building the list of Funcs so [T.M] works in godoc if T is generic. Change-Id: I8ef5264124a944967df3ce20ddd40a2447ff4187 Reviewed-on: https://go-review.googlesource.com/c/go/+/449236 Reviewed-by: Keith Randall <khr@google.com> Reviewed-by: Robert Griesemer <gri@google.com> Run-TryBot: Keith Randall <khr@golang.org> TryBot-Result: Gopher Robot <gobot@golang.org>
* go/doc: use go/doc/commentRuss Cox2022-04-111-1/+131
| | | | | | | | | | | | | | | | | [This CL is part of a sequence implementing the proposal #51082. The design doc is at https://go.dev/s/godocfmt-design.] Use go/doc/comment to implement the existing go/doc comment APIs, as well as adding new APIs more tailored to the new world. For #51082. Change-Id: I05b97ecedbf7cf7b8dede7ace6736ed6d89204a9 Reviewed-on: https://go-review.googlesource.com/c/go/+/384265 Run-TryBot: Russ Cox <rsc@golang.org> Reviewed-by: Jonathan Amsterdam <jba@google.com> TryBot-Result: Gopher Robot <gobot@golang.org> Reviewed-by: Ian Lance Taylor <iant@golang.org>
* all: remove trailing blank doc comment linesRuss Cox2022-04-011-2/+0
| | | | | | | | | | | | | | | | | | | | | | | | A future change to gofmt will rewrite // Doc comment. // func f() to // Doc comment. func f() Apply that change preemptively to all doc comments. For #51082. Change-Id: I4023e16cfb0729b64a8590f071cd92f17343081d Reviewed-on: https://go-review.googlesource.com/c/go/+/384259 Trust: Russ Cox <rsc@golang.org> Run-TryBot: Russ Cox <rsc@golang.org> Reviewed-by: Ian Lance Taylor <iant@golang.org> TryBot-Result: Gopher Robot <gobot@golang.org>
* all: gofmt -w -r 'interface{} -> any' srcRuss Cox2021-12-131-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | And then revert the bootstrap cmd directories and certain testdata. And adjust tests as needed. Not reverting the changes in std that are bootstrapped, because some of those changes would appear in API docs, and we want to use any consistently. Instead, rewrite 'any' to 'interface{}' in cmd/dist for those directories when preparing the bootstrap copy. A few files changed as a result of running gofmt -w not because of interface{} -> any but because they hadn't been updated for the new //go:build lines. Fixes #49884. Change-Id: Ie8045cba995f65bd79c694ec77a1b3d1fe01bb09 Reviewed-on: https://go-review.googlesource.com/c/go/+/368254 Trust: Russ Cox <rsc@golang.org> Run-TryBot: Russ Cox <rsc@golang.org> Reviewed-by: Robert Griesemer <gri@golang.org> TryBot-Result: Gopher Robot <gobot@golang.org>
* go/doc: clarify that NewFromFiles caller must filter by GOOS/GOARCHDmitri Shuralyov2020-02-101-3/+6
| | | | | | | | | | | | | | | | | | | | | | The most well known and important build constraints to take into account when rendering package documentation are the GOOS/GOARCH values. Make it more clear in the NewFromFiles documentation that they are a part of all build constraints that the caller is responsible for filtering out. Also suggest the "go/build".Context.MatchFile method for performing file matching. The logic to perform build context file matching is subtle and has many rules that aren't well known (for example, taking the gc or gccgo compiler into account). It is currently the only exported API in the standard library that implements this logic, and it would be unfortunate if people attempt to re-create it because they don't realize it is already available. Updates #23864 Change-Id: I3c5901e7081acf79125b2d429ec3aa3b58416ed7 Reviewed-on: https://go-review.googlesource.com/c/go/+/218477 Reviewed-by: Robert Griesemer <gri@golang.org>
* go/doc: add NewFromFiles with support for classifying examplesDmitri Shuralyov2019-11-121-1/+103
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This CL is based on work started by Joe Tsai in CL 94855. It's rebased on top of the latest master branch, and addresses various code review comments and findings from attempting to use the original CL in practice. The testing package documents a naming convention for examples so that documentation tools can associate them with: • a package (Example or Example_suffix) • a function F (ExampleF or ExampleF_suffix) • a type T (ExampleT or ExampleT_suffix) • a method T.M (ExampleT_M or ExampleT_M_suffix) This naming convention is in widespread use and enforced via existing go vet checks. This change adds first-class support for classifying examples to go/doc, the package responsible for computing package documentation from Go AST. There isn't a way to supply test files to New that works well. External test files may have a package name with "_test" suffix, so ast.NewPackage may end up using the wrong package name if given test files. A workaround is to add test files to *ast.Package.Files after it is returned from ast.NewPackage: pkg, _ := ast.NewPackage(fset, goFiles, ...) for name, f := range testGoFiles { pkg.Files[name] = f } p := doc.New(pkg, ...) But that is not a good API. After nearly 8 years, a new entry-point is added to the go/doc package, the function NewFromFiles. It accepts a Go package in the form of a list of parsed Go files (including _test.go files) and an import path. The caller is responsible with filtering out files based on build constraints, as was the case before with New. NewFromFiles computes package documentation from .go files, extracts examples from _test.go files and classifies them. Examples fields are added to Package, Type, and Func. They are documented to only be populated with examples found in _test.go files provided to NewFromFiles. The new behavior is: 1. NewFromFiles computes package documentation from provided parsed .go files. It extracts examples from _test.go files. 2. It assigns each Example to corresponding Package, Type, or Func. 3. It sets the Suffix field in each example to the suffix. 4. Malformed examples are skipped. This change implements behavior that matches the current behavior of existing godoc-like tools, and will enable them to rely on the logic in go/doc instead of reimplementing it themselves. Fixes #23864 Change-Id: Iae834f2ff92fbd1c93a9bb7c2bf47d619bee05cf Reviewed-on: https://go-review.googlesource.com/c/go/+/204830 Run-TryBot: Dmitri Shuralyov <dmitshur@golang.org> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Robert Griesemer <gri@golang.org>
* go/doc: add new mode bit PreserveAST to control clearing of data in ASTRob Pike2018-10-101-4/+9
| | | | | | | | | | | | | | | | | | | | To save memory in godoc, this package routinely clears fields of the AST to avoid keeping data that godoc no longer needs. For other programs, such as cmd/doc, this behavior is unfortunate. Also, one should be able to tell any package like this, "don't change my data". Add a Mode bit, defaulting to off to preserve existing behavior, that allows a client to specify that the AST is inviolate. This is necessary to address some of the outstanding issues in cmd/doc that require, for example, looking at function bodies. Fixes #26835 Change-Id: I01cc97c6addc5ab6abff885fff4bd53454a03bbc Reviewed-on: https://go-review.googlesource.com/c/140958 Reviewed-by: Robert Griesemer <gri@golang.org>
* all: switch to the new deprecation conventionShenghou Ma2015-06-181-1/+2
| | | | | | | | | While we're at it, move some misplaced comment blocks around. Change-Id: I1847d7f1ca1dbb8e5de737203c4ed6c66e112508 Reviewed-on: https://go-review.googlesource.com/10188 Reviewed-by: Rob Pike <r@golang.org> Reviewed-by: Russ Cox <rsc@golang.org>
* build: move package sources from src/pkg to srcRuss Cox2014-09-081-0/+111
Preparation was in CL 134570043. This CL contains only the effect of 'hg mv src/pkg/* src'. For more about the move, see golang.org/s/go14nopkg.