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>
The current cmd/doc implementation uses go/build.Import in a few
places to check whether a package is findable and importable.
go/build has limited support for finding packages in modules,
but to do so, build.Import requires knowing the source directory
to use when performing the lookup (so it can find the go.mod file).
Otherwise, it only looks inside the GOPATH workspace.
Start passing the current working directory to build.Import calls,
so that it can correctly look for packages in modules when in cmd/doc
is executed in module mode.
Before this change, cmd/doc in module mode could mistakenly find and
use a package in the GOPATH workspace, instead of the current module.
Since the result of os.Getwd is needed in even more places, assign it
to a local variable in parseArgs now.
Fixes#28992
Updates #26504
Change-Id: I7571618e18420d2d3b3890cc69ade2d97b1962bf
Reviewed-on: https://go-review.googlesource.com/c/go/+/183991
Run-TryBot: Dmitri Shuralyov <dmitshur@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Bryan C. Mills <bcmills@google.com>
A handful of packages were reimplementing IsExported, so use
token.IsExported instead. This caused the deps test to fail for net/rpc.
However, net/rpc deals with Go types, and go/token is light and fairly
low-level in terms of Go tooling packages, so that's okay.
While at it, replace all uses of ast.IsExported with token.IsExported.
This is more consistent, and also means that the import graphs are
leaner. A couple of files no longer need to import go/ast, for example.
We can't get rid of cmd/compile/internal/types.IsExported, as the
compiler can only depend on go/token as of Go 1.4. However, gc used
different implementations in a couple of places, so consolidate the use
of types.IsExported there.
Finally, we can't get rid of the copied IsExported implementation in
encoding/gob, as go/token depends on it as part of a test. That test
can't be an external test either, so there's no easy way to break the
import cycle.
Overall, this removes about forty lines of unnecessary code.
Change-Id: I86a475b7614261e6a7b0b153d5ca02b9f64a7b2d
Reviewed-on: https://go-review.googlesource.com/c/go/+/172037
Run-TryBot: Daniel Martí <mvdan@mvdan.cc>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Telling whether a string is a valid Go identifier can seem like an easy
task, but it's easy to forget about the edge cases. For example, some
implementations out there forget that an empty string or keywords like
"func" aren't valid identifiers.
Add a simple implementation with proper Unicode support, and start using
it in cmd/cover and cmd/doc. Other pieces of the standard library
reimplement part of this logic, but don't use a "func(string) bool"
signature, so we're leaving them untouched for now.
Add some tests too, to ensure that we actually got these edge cases
correctly.
Since telling whether a string is a valid identifier requires knowing
that it's not a valid keyword, add IsKeyword too. The internal map was
already accessible via Lookup, but "Lookup(str) != IDENT" isn't as easy
to understand as IsKeyword(str). And, as per Josh's suggestion, we could
have IsKeyword (and probably Lookup too) use a perfect hash function
instead of a global map.
Finally, for consistency with these new functions, add IsExported. That
makes go/ast.IsExported a bit redundant, so perhaps it can be deprecated
in favor of go/token.IsExported in the future. Clarify that
token.IsExported doesn't imply token.IsIdentifier, to avoid ambiguity.
Fixes#30064.
Change-Id: I0e0e49215fd7e47b603ebc2b5a44086c51ba57f7
Reviewed-on: https://go-review.googlesource.com/c/go/+/169018
Run-TryBot: Daniel Martí <mvdan@mvdan.cc>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Robert Griesemer <gri@golang.org>
Reviewed-by: Alan Donovan <adonovan@google.com>
It really only matters for types, and the code already worked but was
blocked by a usage check.
Fixes#25595
Change-Id: I823f313b682b37616ea555aee079e2fe39f914c2
Reviewed-on: https://go-review.googlesource.com/c/144357
Reviewed-by: Ian Lance Taylor <iant@golang.org>
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>
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>
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>
Keep searching for a package that is both findable and importable. The
current code would always guarantee that a package was findable but
exited if it was not importable.
Fixes#25478
Change-Id: I237b7dfafb930cae02538c4a2e4d5ce0c1058478
Reviewed-on: https://go-review.googlesource.com/114295
Reviewed-by: Bryan C. Mills <bcmills@google.com>
Reviewed-by: Rob Pike <r@golang.org>
Run-TryBot: Bryan C. Mills <bcmills@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
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>
Before, an argument that started ./ or ../ was not treated as
a package relative to the current directory. Thus
$ cd $GOROOT/src/text
$ go doc ./template
could find html/template as $GOROOT/src/html/./template
is a valid Go source directory.
Fix this by catching such paths and making them absolute before
processing.
Fixes#23383.
Change-Id: Ic2a92eaa3a6328f728635657f9de72ac3ee82afb
Reviewed-on: https://go-review.googlesource.com/98396
Reviewed-by: Ian Lance Taylor <iant@golang.org>
In golang.org/cl/59413, the two-argument behavior of cmd/doc was changed
to use findPackage instead of build.Import, meaning that the tool was
more consistent and useful.
However, it introduced a regression:
$ go doc bytes Foo
doc: no such package: bytes
This is because the directory list search would not find Foo in bytes,
and reach the end of the directory list - thus resulting in a "no such
package" error, since no directory matched our first argument.
Move the "no such package" error out of parseArgs, so that the "loop
until something is printed" loop can have control over it. In
particular, it is useful to know when we have reached the end of the
list without any exact match, yet we did find one package matching
"bytes":
$ go doc bytes Foo
doc: no symbol Foo in package bytes
While at it, make the "no such package" error not be fatal so that we
may test for it. It is important to have the test, as parseArgs may now
return a nil package instead of exiting the entire program, potentially
meaning a nil pointer dereference panic.
Fixes#22810.
Change-Id: I90cc6fd755e2d1675bea6d49a1c13cc18ac9bfb9
Reviewed-on: https://go-review.googlesource.com/78677
Run-TryBot: Daniel Martí <mvdan@mvdan.cc>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Rob Pike <r@golang.org>
strings.LastIndexByte was introduced in go1.5 and it can be used
effectively wherever the second argument to strings.LastIndex is
exactly one byte long.
This avoids generating unnecessary string symbols and saves
a few calls to strings.LastIndex.
Change-Id: I7b5679d616197b055cffe6882a8675d24a98b574
Reviewed-on: https://go-review.googlesource.com/66372
Run-TryBot: Ian Lance Taylor <iant@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>
strings.IndexByte was introduced in go1.2 and it can be used
effectively wherever the second argument to strings.Index is
exactly one byte long.
This avoids generating unnecessary string symbols and saves
a few calls to strings.Index.
Change-Id: I1ab5edb7c4ee9058084cfa57cbcc267c2597e793
Reviewed-on: https://go-review.googlesource.com/65930
Run-TryBot: Ian Lance Taylor <iant@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>
When given one argument, as in
go doc binary.BigEndian
doc would search for the package, but when given two, as in
go doc binary BigEndian
it would not. Fix the inconsistency.
Fixes#18697Fixes#18664
Change-Id: Ib59dc483e8d4f91e6061c77a5ec24d0a50e115f0
Reviewed-on: https://go-review.googlesource.com/59413
Reviewed-by: Aliaksandr Valialkin <valyala@gmail.com>
Reviewed-by: Ian Lance Taylor <iant@golang.org>
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>
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>
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>
Trivial fix: set unexported=true for builtin.
Godoc itself has a similar hack.
Fixes#12541
Change-Id: Ib701f867d117931eb6ec6de223941b52eb6cd4a7
Reviewed-on: https://go-review.googlesource.com/14441
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Refine the documentation in cmd/doc and go help doc.
Fixes#12377.
Change-Id: I670c0a5cf18c9c9d5bb9bb222d8a3dd3722a3934
Reviewed-on: https://go-review.googlesource.com/14121
Reviewed-by: Andrew Gerrand <adg@golang.org>
Change the default behavior when showing the package docs
for a command to elide the symbols. This makes
go doc somecommand
show the top-level package docs only and hide the symbols,
which are probably irrelevant to the user. This has no effect
on explicit requests for internals, such as
go doc somecommand.sometype
The new -cmd flag restores the old behavior.
Fixes#10733.
Change-Id: I4d363081fe7dabf76ec8e5315770ac3609592f80
Reviewed-on: https://go-review.googlesource.com/11953
Reviewed-by: Russ Cox <rsc@golang.org>
Refactor main a bit to make it possible to run tests without an exec every time.
(Makes a huge difference in run time.)
Add a silver test. Not quite golden, since it looks for pieces rather than the
full output, and also includes tests for what should not appear.
Fixes#10920.
Change-Id: I6a4951cc14e61763379754a10b0cc3484d30c267
Reviewed-on: https://go-review.googlesource.com/11272
Reviewed-by: Russ Cox <rsc@golang.org>
Run-TryBot: Rob Pike <r@golang.org>
When go doc is invoked with a single package name argument (e.g. go doc pkgname)
it needs to find the directory of the requested package sources in GOPATH.
GOPATH might contain directories with the same name as the requested package
that do no contain any *.go files. This change makes "go doc" ignore such
directories when looking for possible package directories.
This fixes#10882
Change-Id: Ib3d4ea69a25801c34cbe7b044de9870ba12f9aa8
Reviewed-on: https://go-review.googlesource.com/10190
Reviewed-by: Rob Pike <r@golang.org>
An error in string slice offsets caused the loop to run forever if the
first character in the argument was a period.
Fixes#10833.
Change-Id: Iefb6aac5cff8864fe93d08e2600cb07d82c6f6df
Reviewed-on: https://go-review.googlesource.com/10285
Reviewed-by: Russ Cox <rsc@golang.org>
Print it out much like godoc so there isn't a single block of text.
Print the symbol before its comment and indent the comment so
individual symbols separate visually.
Buffer the output.
Add a -c option to force case-sensitive matching.
Allow two arguments, like godoc, to help disambiguate cases
where path and symbol may be confused.
Improve the documentation printed by go help doc.
Change-Id: If687aad04bbacdf7dbe4bf7636de9fe96f756fd0
Reviewed-on: https://go-review.googlesource.com/9471
Reviewed-by: Russ Cox <rsc@golang.org>
Add the new go doc command to the go command, installed in
the tool directory.
(Still to do: tests)
Fix cmd/dist to remove old "package documentation" code that was
stopping it from including cmd/go/doc.go in the build.
Implement the doc command. Here is the help info from "go help doc":
===
usage: go doc [-u] [package|[package.]symbol[.method]]
Doc accepts at most one argument, indicating either a package, a symbol within a
package, or a method of a symbol.
go doc
go doc <pkg>
go doc <sym>[.<method>]
go doc [<pkg>].<sym>[.<method>]
Doc interprets the argument to see what it represents, determined by its syntax
and which packages and symbols are present in the source directories of GOROOT and
GOPATH.
The first item in this list that succeeds is the one whose documentation is printed.
For packages, the order of scanning is determined by the file system, however the
GOROOT tree is always scanned before GOPATH.
If there is no package specified or matched, the package in the current directory
is selected, so "go doc" shows the documentation for the current package and
"go doc Foo" shows the documentation for symbol Foo in the current package.
Doc prints the documentation comments associated with the top-level item the
argument identifies (package, type, 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.)
The package paths must be either a qualified path or a proper suffix of a path
(see examples below). The go tool's usual package mechanism does not apply: package
path elements like . and ... are not implemented by go doc.
When matching symbols, lower-case letters match either case but upper-case letters
match exactly.
Examples:
go doc
Show documentation for current package.
go doc Foo
Show documentation for Foo in the current package.
(Foo starts with a capital letter so it cannot match a package path.)
go doc json
Show documentation for the encoding/json package.
go doc json
Shorthand for encoding/json assuming only one json package
is present in the tree.
go doc json.Number (or go doc json.number)
Show documentation and method summary for json.Number.
go doc json.Number.Int64 (or go doc json.number.int64)
Show documentation for the Int64 method of json.Number.
Flags:
-u
Show documentation for unexported as well as exported
symbols and methods.
===
Still to do:
Tests.
Disambiguation when there is both foo and Foo.
Flag for case-sensitive matching.
Change-Id: I83d409a68688a5445f54297a7e7c745f749b9e66
Reviewed-on: https://go-review.googlesource.com/9227
Reviewed-by: Russ Cox <rsc@golang.org>
Jay Conrod
Gert Cuykens
Dmitri Shuralyov
Daniel Martí
Rob Pike
Russ Cox
Michael Fraenkel
Marvin Stenger
Konstantin Shaposhnikov