This is a subset of https://golang.org/cl/20022 with only the copyright
header lines, so the next CL will be smaller and more reviewable.
Go policy has been single space after periods in comments for some time.
The copyright header template at:
https://golang.org/doc/contribute.html#copyright
also uses a single space.
Make them all consistent.
Change-Id: Icc26c6b8495c3820da6b171ca96a74701b4a01b0
Reviewed-on: https://go-review.googlesource.com/20111
Run-TryBot: Brad Fitzpatrick <bradfitz@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>
Reviewed-by: Matthew Dempsky <mdempsky@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
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>
This is a simple change to the command that should resolve problems like finding
vendored packages before their non-vendored siblings. By searching in breadth-first
order, we find the matching package lowest in the hierarchy, which is more likely
to be correct than the deeper one, such as a vendored package, that will be found
in a depth-first scan.
This may be sufficient to resolve the issue, and has the merit that it is very easy
to explain. I will leave the issue open for now in case my intuition is wrong.
Update #12423
Change-Id: Icf69e8beb1845277203fcb7d19ffb7cca9fa41f5
Reviewed-on: https://go-review.googlesource.com/17691
Reviewed-by: Russ Cox <rsc@golang.org>
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>
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>
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>
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>
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>
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>
People use 80-column terminals because their grandparents used
punched cards. When I last used a punched card, in 1978, it seemed
antiquated even then. But today, people still set their terminal
widths to 80 to honor the struggles their fallen ancestors made to
endure this painful technology.
We must all stand and salute the 80 column flag, or risk the opprobium
of our peers.
For Pete's sake, I don't even use a fixed-width font. I don't even
believe in columns.
Fixes#11639 with extreme reluctance.
P.S. To avoid the horror of an automatically folded line of text, this commit message has been formatted to fit on an 80-column line, except for this postscript.
Change-Id: Ia2eb2dcf293dabe804c22ee5abb4bbb703f45c33
Reviewed-on: https://go-review.googlesource.com/12011
Reviewed-by: Ian Lance Taylor <iant@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>
Some of those consts were supposed to be vars.
Caught by Ingo Oeser.
Change-Id: Ifc12e4a8ee61ebf5174e4ad923956c546dc096e2
Reviewed-on: https://go-review.googlesource.com/11296
Reviewed-by: Andrew Gerrand <adg@golang.org>
Most important: skip test on darwin/arm64 for unclear reasons.
First cut at the test missed this feature of go doc: when asking for
the docs for a type, include any function that looks like it constructs
a that type as a return value.
Change-Id: I124e7695e5d365e2b12524b541a9a4e6e0300fbc
Reviewed-on: https://go-review.googlesource.com/11295
Reviewed-by: Rob Pike <r@golang.org>
nacl is really giving a hard time. avoid all external dependencies in the test.
Worked with trybots, failed in the build. No explanation, but this should fix it.
TBR=rsc
Change-Id: Icb644286dbce88f17ee3d96ad90efba34a80a92d
Reviewed-on: https://go-review.googlesource.com/11291
Reviewed-by: Rob Pike <r@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>
The go/doc package doesn't remove unexported entries from const
and var blocks, so we must trim them ourselves.
Fixes#11008
Change-Id: Ibd60d87e09333964e2588340a2ca2b8804bbaa28
Reviewed-on: https://go-review.googlesource.com/10643
Reviewed-by: Russ Cox <rsc@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>
Better layout.
Fixes#10859.
The issue suggests rearranging so the comment comes out
after the methods. I tried this and it looks good but it is less
useful, since the stuff you're probably looking for - the methods
- are scrolled away by the comment. The most important
information should be last because that leaves it on your
screen after the print if the output is long.
Change-Id: I560f992601ccbe2293c347fa1b1018a3f5346c82
Reviewed-on: https://go-review.googlesource.com/10160
Reviewed-by: Russ Cox <rsc@golang.org>
Was otherwise absent unless bound to an exported symbol,
as in the BUG with strings.Title.
Fixes#10781.
Change-Id: I1543137073a9dee9e546bc9d648ca54fc9632dde
Reviewed-on: https://go-review.googlesource.com/9899
Reviewed-by: Russ Cox <rsc@golang.org>
Already done for constants and funcs, but I didn't realize that some
global vars were also not in the global list. This fixes
go doc build.Default
Change-Id: I768bde13a400259df3e46dddc9f58c8f0e993c72
Reviewed-on: https://go-review.googlesource.com/9764
Reviewed-by: Andrew Gerrand <adg@golang.org>
Improving the usability further.
Before:
$ go doc bytes.Read
doc: symbol Read not present in package bytes installed in "bytes"
$
After:
$ go doc bytes.Read
func (b *Buffer) Read(p []byte) (n int, err error)
Read reads the next len(p) bytes from the buffer or until the buffer is drained.
The return value n is the number of bytes read. If the buffer has no data to
return, err is io.EOF (unless len(p) is zero); otherwise it is nil.
func (r *Reader) Read(b []byte) (n int, err error)
$
Change-Id: I646511fada138bd09e9b39820da01a5ccef4a90f
Reviewed-on: https://go-review.googlesource.com/9656
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>
