aboutsummaryrefslogtreecommitdiff
path: root/src/cmd/doc/pkg.go
AgeCommit message (Collapse)Author
2024-01-25all: prealloc slice with possible minimum capabilitiesShulhan
2024-01-08cmd/doc: fix inconsistent receiver nameMehdi Mostafavi
The ToText method of Package is the only one with a receiver declared 'p'; all the rest have 'pkg'. Fix it to be consistent. Change-Id: I2b47c719f4f6f8d87336316b7f80deb1b49e17dc GitHub-Last-Rev: 7d273b4ef0780b7ed8b651c117a28b25bab5bcb1 GitHub-Pull-Request: golang/go#64912 Reviewed-on: https://go-review.googlesource.com/c/go/+/553335 Run-TryBot: Rob Pike <r@golang.org> Reviewed-by: Dmitri Shuralyov <dmitshur@google.com> Auto-Submit: Dmitri Shuralyov <dmitshur@google.com> Reviewed-by: qiulaidongfeng <2645477756@qq.com> Reviewed-by: Matthew Dempsky <mdempsky@google.com> TryBot-Result: Gopher Robot <gobot@golang.org> Reviewed-by: Rob Pike <r@golang.org>
2023-09-07cmd/doc: print bugs with -all flagPascal S. de Kloe
Includes cleanup and deduplication. fixes: #33970 Change-Id: I7e84b3e5c8fb9c560cf0a1f8b7cbb7a6977666aa Reviewed-on: https://go-review.googlesource.com/c/go/+/511935 Reviewed-by: Rob Pike <r@golang.org> Auto-Submit: Ian Lance Taylor <iant@google.com> Reviewed-by: Ian Lance Taylor <iant@google.com> LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com> Reviewed-by: Matthew Dempsky <mdempsky@google.com>
2023-04-10cmd/doc: format field doc comments when printing entire structIan Lance Taylor
cmd/doc passes structs to go/format, but that means that comments on fields within those structs don't look like what cmd/doc prints when asked for a struct field directly. Tweak the field comments so that they look the same either way. Fixes #56592 Change-Id: I198cb7a58e3d8558406c386072c630332f91c6b0 Reviewed-on: https://go-review.googlesource.com/c/go/+/483055 Run-TryBot: Ian Lance Taylor <iant@golang.org> Reviewed-by: David Chase <drchase@google.com> Reviewed-by: Rob Pike <r@golang.org> Reviewed-by: Michael Knyszek <mknyszek@google.com> TryBot-Result: Gopher Robot <gobot@golang.org> Auto-Submit: Ian Lance Taylor <iant@golang.org>
2022-09-06cmd/doc: use strings.Buildercuiweixie
Change-Id: Ib33d1f1c2e9aed0cb9e00bd699c4ae4a2df5dfca Reviewed-on: https://go-review.googlesource.com/c/go/+/428288 Run-TryBot: Rob Pike <r@golang.org> Reviewed-by: Michael Knyszek <mknyszek@google.com> Reviewed-by: Rob Pike <r@golang.org> Auto-Submit: Rob Pike <r@golang.org> Reviewed-by: Damien Neil <dneil@google.com> TryBot-Result: Gopher Robot <gobot@golang.org>
2022-04-11cmd/doc: use new go/doc APIsRuss Cox
[This CL is part of a sequence implementing the proposal #51082. The design doc is at https://go.dev/s/godocfmt-design.] Use the new per-Package go/doc API instead of the top-level functions from go/doc. These handle links better. For #51082. Change-Id: I169b46d973673abdb6f126352c9f1e30f9fe1122 Reviewed-on: https://go-review.googlesource.com/c/go/+/384266 Run-TryBot: Russ Cox <rsc@golang.org> Reviewed-by: Jonathan Amsterdam <jba@google.com> Reviewed-by: Ian Lance Taylor <iant@golang.org> TryBot-Result: Gopher Robot <gobot@golang.org>
2022-03-17cmd/doc: use 'go env' to identify GOROOT if it isn't otherwise knownBryan C. Mills
Updates #51483. Change-Id: I13d8e58b30639d8a5ed3c9e8b72c8bbaa6a6f1cc Reviewed-on: https://go-review.googlesource.com/c/go/+/391813 Trust: Bryan Mills <bcmills@google.com> Run-TryBot: Bryan Mills <bcmills@google.com> Reviewed-by: Ian Lance Taylor <iant@golang.org> TryBot-Result: Gopher Robot <gobot@golang.org>
2021-12-20cmd/doc: don't log on constraint type elementsIan Lance Taylor
Fixes #50256 Change-Id: I2327a0b28f8173c801ed2946bec8083967667027 Reviewed-on: https://go-review.googlesource.com/c/go/+/373314 Trust: Ian Lance Taylor <iant@golang.org> Run-TryBot: Ian Lance Taylor <iant@golang.org> TryBot-Result: Gopher Robot <gobot@golang.org> Reviewed-by: Robert Findley <rfindley@google.com>
2021-12-13all: gofmt -w -r 'interface{} -> any' srcRuss Cox
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>
2021-11-04cmd/doc, go/doc: add basic support for generic codeRobert Findley
Update cmd/doc and go/doc for the generics, by adding handling for type parameters and the new embedded interface elements. Specifically: - Format type parameters when summarizing type and function nodes. - Find the origin type name for instantiation expressions, so that methods are associated with generic type declarations. - Generalize the handling of embedding 'error' in interfaces to arbitrary predeclared types. - Keep embedded type literals. - Update filtering to descend into embedded type literals. Also add "any" to the list of predeclared types. Updates #49210 Change-Id: I6ea82869f19c3cdbc3c842f01581c8fc7e1c2ee7 Reviewed-on: https://go-review.googlesource.com/c/go/+/359778 Trust: Robert Findley <rfindley@google.com> Run-TryBot: Robert Findley <rfindley@google.com> TryBot-Result: Go Bot <gobot@golang.org> Reviewed-by: Robert Griesemer <gri@golang.org>
2021-10-06all: use bytes.Cut, strings.CutRuss Cox
Many uses of Index/IndexByte/IndexRune/Split/SplitN can be written more clearly using the new Cut functions. Do that. Also rewrite to other functions if that's clearer. For #46336. Change-Id: I68d024716ace41a57a8bf74455c62279bde0f448 Reviewed-on: https://go-review.googlesource.com/c/go/+/351711 Trust: Russ Cox <rsc@golang.org> Run-TryBot: Russ Cox <rsc@golang.org> TryBot-Result: Go Bot <gobot@golang.org> Reviewed-by: Ian Lance Taylor <iant@golang.org>
2021-03-19cmd/doc: properly display interface methodsAgniva De Sarker
Previously, we used to call doc.ToText to print each comment in a comment group attached to an interface method. This broke any preformatted code block attached to the comment, and displayed everything aligned to a single column. Additionally, the name of the interface also wasn't displayed which didn't show which interface the method belonged to. To fix this, we print the entire interface node using format.Node which takes care of displaying the comments correctly, and we also filter out the methods that don't match, so that the method can be displayed as belonging to an interface. As an example, previously it would show: // Comment before exported method. // // // Code block showing how to use ExportedMethod // func DoSomething() error { // ExportedMethod() // return nil // } func ExportedMethod() // Comment on line with exported method. Now, it shows: type ExportedInterface interface { // Comment before exported method. // // // Code block showing how to use ExportedMethod // func DoSomething() error { // ExportedMethod() // return nil // } ExportedMethod() // Comment on line with exported method. } Fixes #43188 Change-Id: I28099fe4aab35e08049b2616a3506240f57133cc Reviewed-on: https://go-review.googlesource.com/c/go/+/279433 Trust: Agniva De Sarker <agniva.quicksilver@gmail.com> Trust: Daniel Martí <mvdan@mvdan.cc> Reviewed-by: Rob Pike <r@golang.org>
2020-10-20all: update references to symbols moved from os to io/fsRuss Cox
The old os references are still valid, but update our code to reflect best practices and get used to the new locations. Code compiled with the bootstrap toolchain (cmd/asm, cmd/dist, cmd/compile, debug/elf) must remain Go 1.4-compatible and is excluded. For #41190. Change-Id: I8f9526977867c10a221e2f392f78d7dec073f1bd Reviewed-on: https://go-review.googlesource.com/c/go/+/243907 Trust: Russ Cox <rsc@golang.org> Run-TryBot: Russ Cox <rsc@golang.org> TryBot-Result: Go Bot <gobot@golang.org> Reviewed-by: Rob Pike <r@golang.org>
2020-04-17cmd/doc: don't print package clauses on errorRob Pike
Everybody was deferring a flush when main already did that, so drop all that nonsense. (Flush was doing the package clause stuff.) But then make sure we do get a package clause when there is correctly no output, as for an empty package. Do that by triggering a package clause in allDoc and packageDoc. Slightly tricky but way less intricate than before. Fixes #37969. Change-Id: Ia86828436e6c4ab46e6fdaf2c550047f37f353f3 Reviewed-on: https://go-review.googlesource.com/c/go/+/226998 Reviewed-by: Russ Cox <rsc@golang.org>
2019-11-12cmd/doc: show the package clause alwaysAgniva De Sarker
If no writes to the package buffer happen, then the package clause does not get printed. This is a bug for cases where a file just contains the package clause. We fix this by separating the printing of package clause to a new function and calling it from (*pkgBuffer).Write as well as (*Package).flush. Updates #31457 Change-Id: Ia3bd0ea3963274c460a45d1e37fafc6ee0a197f0 Reviewed-on: https://go-review.googlesource.com/c/go/+/206128 Run-TryBot: Agniva De Sarker <agniva.quicksilver@gmail.com> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Rob Pike <r@golang.org>
2019-11-12cmd/doc: show variables of unexported types for -allAgniva De Sarker
We use the typedValue map to prevent showing typed variables and constants from appearing in the VARIABLES/CONSTANTS section because they will be anyways shown in the TYPES section for that type. However, when a type is unexported, but the variable is exported, then unconditionally setting it to true in the map suppresses it from being shown in the VARIABLES section. Thus, we set the variable or constant in the typedValue map only when the type name is exported. Fixes #31067 Change-Id: Id3ec4b313c9ea7e3ce6fe279680d56f65451719f Reviewed-on: https://go-review.googlesource.com/c/go/+/206129 Run-TryBot: Agniva De Sarker <agniva.quicksilver@gmail.com> Reviewed-by: Rob Pike <r@golang.org> TryBot-Result: Gobot Gobot <gobot@golang.org>
2019-09-19cmd/doc: add option to output a clean one-line symbol representationGert Cuykens
Currently there is no way for go doc to output a clean one-line symbol representation of types, functions, vars and consts without documentation lines or other text lines added. For example `go doc fmt` has a huge introduction so if you pass that to grep or fzf to search a symbol let say scan `go doc fmt | grep scan` you get way to many false positives. Added a `-short` flag to be able to do `go doc -short fmt | grep scan` instead which will result in just the symbols you are looking for. func Fscan(r io.Reader, a ...interface{}) (n int, err error) func Fscanf(r io.Reader, format string, a ...interface{}) (n int, err error) func Fscanln(r io.Reader, a ...interface{}) (n int, err error) func Sscan(str string, a ...interface{}) (n int, err error) func Sscanf(str string, format string, a ...interface{}) (n int, err error) func Sscanln(str string, a ...interface{}) (n int, err error) Fixes #32597 Change-Id: I77a73838adc512c8d1490f5a82075de6b0462a31 Reviewed-on: https://go-review.googlesource.com/c/go/+/184017 Run-TryBot: Andrew Bonventre <andybons@golang.org> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Andrew Bonventre <andybons@golang.org>
2019-05-28cmd/doc: always print package clause except for commandsRob Pike
There was an implicit heuristic before about when to print the package clause or omit it, but it was undocumented and confusing. Get rid of it and print it always unless asking for the package docs for a command, which are more of a usage message than a programming question. This simplifies the processing. There are several paths to the output, so to put the fix in one place we place a wrapper before the output buffer than adds the clause when Write is first called. The tests don't verify this behavior, but they didn't before either. Unsure what the right approach is but this will do for now. Fixes #31457 Change-Id: Ia6a9e740d556f45265c55f06b5306621c7a40ea9 Reviewed-on: https://go-review.googlesource.com/c/go/+/177797 Reviewed-by: Russ Cox <rsc@golang.org>
2019-05-25cmd/doc: display a proper error when no packages are foundAgniva De Sarker
Fixes #32044 Change-Id: Ia220dbbe4d6851befe28dd2d4b8a1a7bc2757460 Reviewed-on: https://go-review.googlesource.com/c/go/+/178878 Run-TryBot: Agniva De Sarker <agniva.quicksilver@gmail.com> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Rob Pike <r@golang.org>
2019-05-23cmd/doc: stop showing interface methods while matching symbolsAgniva De Sarker
Fixes #31961 Change-Id: I9db9ecfd2f8ca7cf51df4413a6e0d66de5da7043 Reviewed-on: https://go-review.googlesource.com/c/go/+/178457 Run-TryBot: Agniva De Sarker <agniva.quicksilver@gmail.com> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Rob Pike <r@golang.org>
2019-03-31cmd/doc: correctly indent pre-formatted blocksSegev Finer
They were previously indented at the same level as the normal text when printing a single symbol or the description of a field. Running "go doc text/template Must": Before: func Must(t *Template, err error) *Template Must is a helper that wraps a call to a function returning (*Template, error) and panics if the error is non-nil. It is intended for use in variable initializations such as var t = template.Must(template.New("name").Parse("text")) After: func Must(t *Template, err error) *Template Must is a helper that wraps a call to a function returning (*Template, error) and panics if the error is non-nil. It is intended for use in variable initializations such as var t = template.Must(template.New("name").Parse("text")) Running "go doc http Request.Header": Before: type Request struct { // Header contains the request header fields either received // by the server or to be sent by the client. // // If a server received a request with header lines, // // Host: example.com // accept-encoding: gzip, deflate // Accept-Language: en-us // fOO: Bar // foo: two // // then // // Header = map[string][]string{ // "Accept-Encoding": {"gzip, deflate"}, // "Accept-Language": {"en-us"}, // "Foo": {"Bar", "two"}, // } ... After: type Request struct { // Header contains the request header fields either received by the server or // to be sent by the client. // // If a server received a request with header lines, // // Host: example.com // accept-encoding: gzip, deflate // Accept-Language: en-us // fOO: Bar // foo: two // // then // // Header = map[string][]string{ // "Accept-Encoding": {"gzip, deflate"}, // "Accept-Language": {"en-us"}, // "Foo": {"Bar", "two"}, // } ... Fixes #29708 Change-Id: Ibe1a6a7a76d6b19c5737ba6e8210e3ad0b88ce16 GitHub-Last-Rev: 439c0fe70a01490cbd9c3613eba3fe45a3ffd9be GitHub-Pull-Request: golang/go#31120 Reviewed-on: https://go-review.googlesource.com/c/go/+/169957 Run-TryBot: Rob Pike <r@golang.org> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Rob Pike <r@golang.org>
2019-03-08cmd/doc: add a line gap after a method with no commentAgniva De Sarker
Fixes #30492 Change-Id: Iec658bdf8bfac21e1bcc3eed900722cc535ec00a Reviewed-on: https://go-review.googlesource.com/c/go/+/166178 Run-TryBot: Agniva De Sarker <agniva.quicksilver@gmail.com> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Rob Pike <r@golang.org>
2018-10-18cmd/doc: minor code simplificationRobert Griesemer
Follow-up on https://golang.org/cl/143037. Change-Id: Ia36760b499f7d46ce03e0fa81ec455a4a20208ac Reviewed-on: https://go-review.googlesource.com/c/143061 Run-TryBot: Robert Griesemer <gri@golang.org> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Rob Pike <r@golang.org>
2018-10-18cmd/doc: make comments inside functions appear with -srcRob Pike
The old godoc didn't do this either, perhaps because it's a little tricky, but it can be done using a special type from the go/printer package. (Usually we just use go/format). Fixes #28195. Change-Id: Ic6d3df3953ba71128398ceaf9a133c798551b6b8 Reviewed-on: https://go-review.googlesource.com/c/143037 Reviewed-by: Robert Griesemer <gri@golang.org>
2018-10-17cmd/doc: fix repeated header bug added in previous CLRob Pike
One too many lines was deleted, and it would print a header multiple times. Add a test. Change-Id: I4906b454dbb66193d515ffacf43849ffdc2dede6 Reviewed-on: https://go-review.googlesource.com/c/142937 Reviewed-by: Ralph Corderoy <ralph@inputplus.co.uk> Reviewed-by: Daniel Martí <mvdan@mvdan.cc> Run-TryBot: Daniel Martí <mvdan@mvdan.cc> TryBot-Result: Gobot Gobot <gobot@golang.org>
2018-10-17cmd/doc: add -all flag to print all documentation for packageRob Pike
Unlike the one for the old godoc, you need the -u flag to see unexported symbols. This seems like the right behavior: it's consistent. For now at least, the argument must be a package, not a symbol. This is also different from old godoc. Required a little refactoring but also cleaned up a few things. Update #25595 Leaving the bug open for now until we tackle go doc -all symbol Change-Id: Ibc1975bfa592cb1e92513eb2e5e9e11e01a60095 Reviewed-on: https://go-review.googlesource.com/c/141977 Run-TryBot: Rob Pike <r@golang.org> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Russ Cox <rsc@golang.org>
2018-10-10cmd/doc: add a -src flag to show original sourceRob Pike
It's long-desired but was blocked by #26835. That is now fixed, so it's easy. When -src is off, we behave as before. But with -src set, initialize the go/doc package to preserve the original AST and things flow very easily. With -src, since you're seeing inside the package source anyway it shows unexported fields and constants: you see the original source. But you still need -u to ask about them. Fixes #18807 Change-Id: I473e90323b4eff0735360274dc0d2d9dba16ff8b Reviewed-on: https://go-review.googlesource.com/c/140959 Reviewed-by: Andrew Gerrand <adg@golang.org> Run-TryBot: Andrew Gerrand <adg@golang.org> TryBot-Result: Gobot Gobot <gobot@golang.org>
2018-08-01cmd/doc: adapt directory search for modulesRuss Cox
Previously, cmd/doc treated GOROOT/src and GOPATH/src as the roots of the directory trees holding packages, assuming that the import path would be the path elements after the src directory. With modules, each module serves as its own root of a file tree, and the import path prefix starts with the module path before adding the path elements after the module root. There are ways we could make this more efficient, but for now this is a fairly small adjustment to get 'go doc' working OK for modules for Go 1.11. Fixes #26635. Change-Id: Ifdee4194601312846c7b1fc67f2fe7a4a44269cc Reviewed-on: https://go-review.googlesource.com/126799 Run-TryBot: Russ Cox <rsc@golang.org> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Rob Pike <r@golang.org>
2018-03-21cmd/doc: use empty GOPATH when running the testsDaniel Martí
Otherwise, a populated GOPATH might result in failures such as: $ go test [...] no buildable Go source files in [...]/gopherjs/compiler/natives/src/crypto/rand exit status 1 Move the initialization of the dirs walker out of the init func, so that we can control its behavior in the tests. Updates #24464. Change-Id: I4b26a7d3d6809bdd8e9b6b0556d566e7855f80fe Reviewed-on: https://go-review.googlesource.com/101836 Run-TryBot: Daniel Martí <mvdan@mvdan.cc> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Ian Lance Taylor <iant@golang.org>
2018-02-26cmd: avoid unnecessary type conversionsKunpei Sakai
CL generated mechanically with github.com/mdempsky/unconvert. Also updated cmd/compile/internal/ssa/gen/*.rules manually. Change-Id: If721ef73cf0771ae83ce7e2d11623fc8d9155768 Reviewed-on: https://go-review.googlesource.com/97075 Reviewed-by: Matthew Dempsky <mdempsky@google.com> Run-TryBot: Matthew Dempsky <mdempsky@google.com> TryBot-Result: Gobot Gobot <gobot@golang.org>
2017-12-20cmd/doc: suppress the error message for *package.ident embedded in struct typeelpinal
The current implementation prints a log, "invalid program: unexpected type for embedded field", when the form *package.ident is embedded in a struct declaration. Note that since valid qualified identifiers must be exported, the result for a valid program does not change. Change-Id: If8b9d7056c56b6a6c5482eb749168a63c65ef685 Reviewed-on: https://go-review.googlesource.com/84436 Reviewed-by: Robert Griesemer <gri@golang.org> Run-TryBot: Robert Griesemer <gri@golang.org> TryBot-Result: Gobot Gobot <gobot@golang.org>
2017-11-20cmd/doc: don't print a declaration twiceRob Pike
That can occur if we have -u set and there is an upper- and lower-case name of the same spelling in a single declaration. A rare corner case but easy to fix. Fix by remembering what we've printed. Fixes #21797. Change-Id: Ie0b681ae8c277fa16e9635ba594c1dff272b8aeb Reviewed-on: https://go-review.googlesource.com/78715 Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org> Run-TryBot: Brad Fitzpatrick <bradfitz@golang.org> TryBot-Result: Gobot Gobot <gobot@golang.org>
2017-07-06cmd/doc: print Go syntax when printing struct.field docsBrad Fitzpatrick
Fixes #20928 Change-Id: I7f7aafb8ff4b5deb50c286a9ae81c34ee85e56a9 Reviewed-on: https://go-review.googlesource.com/47730 Reviewed-by: Rob Pike <r@golang.org> Run-TryBot: Brad Fitzpatrick <bradfitz@golang.org> TryBot-Result: Gobot Gobot <gobot@golang.org>
2017-03-22cmd/doc: implement "go doc struct.field"Rob Pike
By analogy with the handling of methods on types, show the documentation for a single field of a struct. % go doc ast.structtype.fields struct StructType { Fields *FieldList // list of field declarations } % Fixes #19169. Change-Id: I002f992e4aa64bee667e2e4bccc7082486149842 Reviewed-on: https://go-review.googlesource.com/38438 Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org> Run-TryBot: Brad Fitzpatrick <bradfitz@golang.org> TryBot-Result: Gobot Gobot <gobot@golang.org>
2017-02-24cmd/doc: truncate long lists of argumentsJoe Tsai
Some field-lists (especially in generated code) can be excessively long. In the one-line printout, it does not make sense to print all elements of the list if line-wrapping causes the "one-line" to become multi-line. // Before: var LongLine = newLongLine("someArgument1", "someArgument2", "someArgument3", "someArgument4", "someArgument5", "someArgument6", "someArgument7", "someArgument8") // After: var LongLine = newLongLine("someArgument1", "someArgument2", "someArgument3", "someArgument4", ...) Change-Id: I4bbbe2dbd1d7be9f02d63431d213088c3dee332c Reviewed-on: https://go-review.googlesource.com/36031 Run-TryBot: Joe Tsai <thebrokentoaster@gmail.com> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Rob Pike <r@golang.org>
2017-01-25[dev.typealias] cmd/doc: update for type aliasRuss Cox
For #18130. Change-Id: I06b05a2b45a2aa6764053fc51e05883063572dad Reviewed-on: https://go-review.googlesource.com/35670 Run-TryBot: Russ Cox <rsc@golang.org> Reviewed-by: Robert Griesemer <gri@golang.org>
2016-10-25cmd/doc: show documentation for interface methods when requested explicitlyRob Pike
For historical reasons, the go/doc package does not include the methods within an interface as part of the documented methods for that type. Thus, go doc ast.Node.Pos gives an incorrect and confusing error message: doc: no method Node.Pos in package go/ast This CL does some dirty work to dig down to the methods so interface methods now present their documentation: % go doc ast.node.pos func Pos() token.Pos // position of first character belonging to the node % It must largely sidestep the doc package to do this, which is a shame. Perhaps things will improve there one day. The change does not handle embeddings, and in principle the same approach could be done for struct fields, but that is also not here yet. But this CL fixes the thing that was bugging me. Change-Id: Ic10a91936da96f54ee0b2f4a4fe4a8c9b93a5b4a Reviewed-on: https://go-review.googlesource.com/31852 Reviewed-by: Robert Griesemer <gri@golang.org>
2016-10-05cmd/doc: ensure summaries truly are only one lineJoe Tsai
The documentation for doc says: > Doc prints the documentation comments associated with the item identified by its > arguments (a package, const, func, type, var, or method) followed by a one-line > summary of each of the first-level items "under" that item (package-level > declarations for a package, methods for a type, etc.). Certain variables (and constants, functions, and types) have value specifications that are multiple lines long. Prior to this change, doc would print out all of the lines necessary to display the value. This is inconsistent with the documented behavior, which guarantees a one-line summary for all first-level items. We fix this here by writing a general oneLineNode method that always returns a one-line summary (guaranteed!) of any input node. Packages like image/color/palette and unicode now become much more readable since large slices are now a single line. $ go doc image/color/palette <<< // Before: var Plan9 = []color.Color{ color.RGBA{0x00, 0x00, 0x00, 0xff}, color.RGBA{0x00, 0x00, 0x44, 0xff}, color.RGBA{0x00, 0x00, 0x88, 0xff}, ... // Hundreds of more lines! } var WebSafe = []color.Color{ color.RGBA{0x00, 0x00, 0x00, 0xff}, color.RGBA{0x00, 0x00, 0x33, 0xff}, color.RGBA{0x00, 0x00, 0x66, 0xff}, ... // Hundreds of more lines! } // After: var Plan9 = []color.Color{ ... } var WebSafe = []color.Color{ ... } >>> In order to test this, I ran `go doc` and `go doc -u` on all of the standard library packages and diff'd the output with and without the change to ensure that all differences were intended. Fixes #13072 Change-Id: Ida10b7796b7e4e174a929b55c60813a9eb7158fe Reviewed-on: https://go-review.googlesource.com/25420 Run-TryBot: Joe Tsai <thebrokentoaster@gmail.com> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Rob Pike <r@golang.org>
2016-09-30cmd/doc: perform type grouping for constants and variablesJoe Tsai
In golang.org/cl/22354, we added functionality to group functions under the type that they construct to. In this CL, we extend the same concept to constants and variables. This makes the doc tool more consistent with what the godoc website does. $ go doc reflect | egrep "ChanDir|Kind|SelectDir" <<< // Before: const RecvDir ChanDir = 1 << iota ... const Invalid Kind = iota ... type ChanDir int type Kind uint type SelectDir int func ChanOf(dir ChanDir, t Type) Type // After: type ChanDir int const RecvDir ChanDir = 1 << iota ... type Kind uint const Invalid Kind = iota ... type SelectDir int const SelectSend SelectDir ... func ChanOf(dir ChanDir, t Type) Type >>> Furthermore, a fix was made to ensure that the type was printed in constant blocks when the iota was applied on an unexported field. $ go doc reflect SelectSend <<< // Before: const ( SelectSend // case Chan <- Send SelectRecv // case <-Chan: SelectDefault // default ) // After: const ( SelectSend SelectDir // case Chan <- Send SelectRecv // case <-Chan: SelectDefault // default ) >>> Fixes #16569 Change-Id: I26124c3d19e50caf9742bb936803a665e0fa6512 Reviewed-on: https://go-review.googlesource.com/25419 Reviewed-by: Rob Pike <r@golang.org> Run-TryBot: Joe Tsai <thebrokentoaster@gmail.com> TryBot-Result: Gobot Gobot <gobot@golang.org>
2016-08-02cmd/doc: ensure functions with unexported return values are shownJoe Tsai
The commit in golang.org/cl/22354 groups constructors functions under the type that they construct to. However, this caused a minor regression where functions that had unexported return values were not being printed at all. Thus, we forgo the grouping logic if the type the constructor falls under is not going to be printed. Fixes #16568 Change-Id: Idc14f5d03770282a519dc22187646bda676af612 Reviewed-on: https://go-review.googlesource.com/25369 Run-TryBot: Joe Tsai <thebrokentoaster@gmail.com> Reviewed-by: Rob Pike <r@golang.org> TryBot-Result: Gobot Gobot <gobot@golang.org>
2016-08-02cmd/doc: handle embedded interfaces properlyJoe Tsai
Changes made: * Disallow star expression on interfaces as this is not possible. * Show an embedded "error" in an interface as public similar to how godoc does it. * Properly handle selector expressions in both structs and interfaces. This is possible since a type may refer to something defined in another package (e.g. io.Reader). Before: <<< $ go doc runtime.Error type Error interface { // RuntimeError is a no-op function but // serves to distinguish types that are run time // errors from ordinary errors: a type is a // run time error if it has a RuntimeError method. RuntimeError() // Has unexported methods. } $ go doc compress/flate Reader doc: invalid program: unexpected type for embedded field doc: invalid program: unexpected type for embedded field type Reader interface { io.Reader io.ByteReader } >>> After: <<< $ go doc runtime.Error type Error interface { error // RuntimeError is a no-op function but // serves to distinguish types that are run time // errors from ordinary errors: a type is a // run time error if it has a RuntimeError method. RuntimeError() } $ go doc compress/flate Reader type Reader interface { io.Reader io.ByteReader } >>> Fixes #16567 Change-Id: I272dede971eee9f43173966233eb8810e4a8c907 Reviewed-on: https://go-review.googlesource.com/25365 Reviewed-by: Rob Pike <r@golang.org> Run-TryBot: Joe Tsai <thebrokentoaster@gmail.com> TryBot-Result: Gobot Gobot <gobot@golang.org>
2016-04-21cmd/doc: group constructors with type in package presentationRob Pike
Fixes #14004. $ go doc encoding.gob Before: func Register(value interface{}) func RegisterName(name string, value interface{}) func NewDecoder(r io.Reader) *Decoder func NewEncoder(w io.Writer) *Encoder type CommonType struct { ... } type Decoder struct { ... } type Encoder struct { ... } type GobDecoder interface { ... } type GobEncoder interface { ... } After: func Register(value interface{}) func RegisterName(name string, value interface{}) type CommonType struct { ... } type Decoder struct { ... } func NewDecoder(r io.Reader) *Decoder type Encoder struct { ... } func NewEncoder(w io.Writer) *Encoder type GobDecoder interface { ... } type GobEncoder interface { ... } Change-Id: I021db25bce4a16b3dfa22ab323ca1f4e68d50111 Reviewed-on: https://go-review.googlesource.com/22354 Reviewed-by: Robert Griesemer <gri@golang.org>
2016-03-25all: delete dead non-test codeDominik Honnef
This change removes a lot of dead code. Some of the code has never been used, not even when it was first commited. The rest shouldn't have survived refactors. This change doesn't remove unused routines helpful for debugging, nor does it remove code that's used in commented out blocks of code that are only unused temporarily. Furthermore, unused constants weren't removed when they were part of a set of constants from specifications. One noteworthy omission from this CL are about 1000 lines of unused code in cmd/fix, 700 lines of which are the typechecker, which hasn't been used ever since the pre-Go 1 fixes have been removed. I wasn't sure if this code should stick around for future uses of cmd/fix or be culled as well. Change-Id: Ib714bc7e487edc11ad23ba1c3222d1fd02e4a549 Reviewed-on: https://go-review.googlesource.com/20926 Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org> Run-TryBot: Brad Fitzpatrick <bradfitz@golang.org> TryBot-Result: Gobot Gobot <gobot@golang.org>
2016-02-22cmd/doc: handle embedded fields properlyRob Pike
The structure of the code meant that an embedded field was never checked for export status. We need to check the name of the type, which is either of type T or type *T, and T might be unexported. Fixes #14356. Change-Id: I56f468e9b8ae67e9ed7509ed0b91d860507baed2 Reviewed-on: https://go-review.googlesource.com/19701 Reviewed-by: Robert Griesemer <gri@golang.org>
2015-11-17cmd/doc: fix strange indentation artifacts with unexported fieldsJoe Tsai
The NamePos value was not being set, and would default to a value of zero. This would cause the printing logic to get confused as to where exactly to place the "Has unexported fields" string. A trivial package changes from < type A struct { A int // A B int // B // Has unexported fields. } > to < type A struct { A int // A B int // B // Has unexported fields. } > Fixes #12971 Change-Id: I53b7799a1f1c0ad7dcaddff83d9aaeb1d6b7823e Reviewed-on: https://go-review.googlesource.com/16286 Run-TryBot: Joe Tsai <joetsai@digital-static.net> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Rob Pike <r@golang.org>
2015-09-29cmd/doc: fix pretty printing of pathsRob Pike
The code to strip GOROOT and GOPATH had a bug: it assumed there were bytes after the GOROOT prefix but there might not be. Fix this and other issues by taking care the prefix is really a file name prefix for the path, not just a string prefix, and handle the case where GOROOT==path. Change-Id: I8066865fd05f938bb6dbf3bb8ab1fc58e5cf6bb5 Reviewed-on: https://go-review.googlesource.com/15112 Run-TryBot: Rob Pike <r@golang.org> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Andrew Gerrand <adg@golang.org>
2015-09-28cmd/doc: rearrange the newlines to group betterRob Pike
Main change is that the comment for an item no longer has a blank line before it, so it looks bound to the item it's about. Motivating example: go doc.io.read changes from < func (l *LimitedReader) Read(p []byte) (n int, err error) func (r *PipeReader) Read(data []byte) (n int, err error) Read implements the standard Read interface: it reads data from the pipe, blocking until a writer arrives or the write end is closed. If the write end is closed with an error, that error is returned as err; otherwise err is EOF. func (s *SectionReader) Read(p []byte) (n int, err error) > to < func (l *LimitedReader) Read(p []byte) (n int, err error) func (r *PipeReader) Read(data []byte) (n int, err error) Read implements the standard Read interface: it reads data from the pipe, blocking until a writer arrives or the write end is closed. If the write end is closed with an error, that error is returned as err; otherwise err is EOF. func (s *SectionReader) Read(p []byte) (n int, err error) > Now the comment about PipeReader.Read doesn't look like it's about SectionReader. Based on a suggestion by dsnet@, a slight tweak from a CL he suggested and abandoned. Fixes #12756, Change-Id: Iaf60ee9ae7f644c83c32d5e130acab0312b0c926 Reviewed-on: https://go-review.googlesource.com/14999 Reviewed-by: Andrew Gerrand <adg@golang.org>
2015-09-24cmd/doc: don't stop after first package if the symbol is not foundRob Pike
The test case is go doc rand.Float64 The first package it finds is crypto/rand, which does not have a Float64. Before this change, cmd/doc would stop there even though math/rand has the symbol. After this change, we get: % go doc rand.Float64 package rand // import "math/rand" func Float64() float64 Float64 returns, as a float64, a pseudo-random number in [0.0,1.0) from the default Source. % Another nice consequence is that if a symbol is not found, we might get a longer list of packages that were examined: % go doc rand.Int64 doc: no symbol Int64 in packages crypto/rand, math/rand exit status 1 % This change introduces a coroutine to scan the file system so that if the symbol is not found, the coroutine can deliver another path to try. (This is darned close to the original motivation for coroutines.) Paths are delivered on an unbuffered channel so the scanner does not proceed until candidate paths are needed. The scanner is attached to a new type, called Dirs, that caches the results so if we need to scan a second time, we don't walk the file system again. This is significantly more efficient than the existing code, which could scan the tree multiple times looking for a package with the symbol. Change-Id: I2789505b9992cf04c19376c51ae09af3bc305f7f Reviewed-on: https://go-review.googlesource.com/14921 Reviewed-by: Andrew Gerrand <adg@golang.org>
2015-09-21cmd/doc: don't drop const/var block if first entry is unexportedRob Pike
The code assumed that if the first entry was unexported, all the entries were. The fix is simple: delete a bunch of code. Fixes #12286. Change-Id: Icb09274e99ce97df4d8bddbe59d17a5c0622e4c6 Reviewed-on: https://go-review.googlesource.com/14780 Reviewed-by: Andrew Gerrand <adg@golang.org>
2015-09-11cmd/doc: slice/map literals janitoringDidier Spezia
Simplify slice/map literal expression. Caught with gofmt -d -s Change-Id: I7f38ef9fb528e2fd284bd0f190fbdf4a91956e55 Reviewed-on: https://go-review.googlesource.com/13834 Reviewed-by: Andrew Gerrand <adg@golang.org>
generated by cgit v1.3 (git 2.53.0) at 2026-04-15 08:15:23 +0000