Issue 61480044: code review 61480044: go.tools/cmd/vet: add stable checks to doc.go (Closed)
Descriptiongo.tools/cmd/vet: add stable checks to doc.go
These are the simplest possible descriptions of each command.
They may be fleshed out later.
Fixes issue 7298.
Patch Set 1 #
Total comments: 2
Patch Set 2 : diff -r c94b6fa807e8 https://code.google.com/p/go.tools #
Total comments: 2
Patch Set 3 : diff -r 3bbdb0ce2660 https://code.google.com/p/go.tools #MessagesTotal messages: 10
Hello r (cc: golang-codereviews@googlegroups.com), I'd like you to review this change to https://code.google.com/p/go.tools
Sign in to reply to this message.
I wonder if this is such a good idea. Should this be in the vet binary itself? It's reasonable to run it outside the go tool; it seems odd (but perhaps justifiable) to have all the documentation be in a different program altogether, far away and likely to become outdated. In short, this could be for details, run go tool vet --help and then help in the vet program could actually say something. It's a question. I'm seeking opinions.
Sign in to reply to this message.
This is the vet tool's doc.go (nothing to do with cmd/go) as viewable here: http://godoc.org/code.google.com/p/go.tools/cmd/vet But we could put these docs into the vet tool's command-line help as well. On 11 February 2014 17:52, <r@golang.org> wrote: > I wonder if this is such a good idea. Should this be in the vet binary > itself? It's reasonable to run it outside the go tool; it seems odd (but > perhaps justifiable) to have all the documentation be in a different > program altogether, far away and likely to become outdated. > > In short, this could be > > for details, run go tool vet --help > > and then help in the vet program could actually say something. > > > It's a question. I'm seeking opinions. > > > > https://codereview.appspot.com/61480044/ >
Sign in to reply to this message.
Yes, I know what it is. I'm asking where the information belongs. It feels fragile and a bit odd to me to have the rich documentation like this far from the program that it describes. -rob On Mon, Feb 10, 2014 at 10:55 PM, Andrew Gerrand <adg@golang.org> wrote: > This is the vet tool's doc.go (nothing to do with cmd/go) as viewable here: > > http://godoc.org/code.google.com/p/go.tools/cmd/vet > > But we could put these docs into the vet tool's command-line help as well. > > > On 11 February 2014 17:52, <r@golang.org> wrote: >> >> I wonder if this is such a good idea. Should this be in the vet binary >> itself? It's reasonable to run it outside the go tool; it seems odd (but >> perhaps justifiable) to have all the documentation be in a different >> program altogether, far away and likely to become outdated. >> >> In short, this could be >> >> for details, run go tool vet --help >> >> and then help in the vet program could actually say something. >> >> >> It's a question. I'm seeking opinions. >> >> >> >> https://codereview.appspot.com/61480044/ > >
Sign in to reply to this message.
"godoc code.google.com/p/go.tools/cmd/vet" also provides these same docs. Since we need to invoke vet with "go tool vet" to use these flags, it seems logical that the docs should be in vet's doc.go file. This change makes sense to me, and I don't really have any other suggestions. On 12 February 2014 02:44, Rob Pike <r@golang.org> wrote: > Yes, I know what it is. I'm asking where the information belongs. It > feels fragile and a bit odd to me to have the rich documentation like > this far from the program that it describes. > > -rob > > > On Mon, Feb 10, 2014 at 10:55 PM, Andrew Gerrand <adg@golang.org> wrote: > > This is the vet tool's doc.go (nothing to do with cmd/go) as viewable > here: > > > > http://godoc.org/code.google.com/p/go.tools/cmd/vet > > > > But we could put these docs into the vet tool's command-line help as > well. > > > > > > On 11 February 2014 17:52, <r@golang.org> wrote: > >> > >> I wonder if this is such a good idea. Should this be in the vet binary > >> itself? It's reasonable to run it outside the go tool; it seems odd (but > >> perhaps justifiable) to have all the documentation be in a different > >> program altogether, far away and likely to become outdated. > >> > >> In short, this could be > >> > >> for details, run go tool vet --help > >> > >> and then help in the vet program could actually say something. > >> > >> > >> It's a question. I'm seeking opinions. > >> > >> > >> > >> https://codereview.appspot.com/61480044/ > > > > >
Sign in to reply to this message.
Sigh. I was arguing that you should do exactly what you did. I read it as being part of the go command's documentation. Brain clouds. I will review now. On Wed, Feb 12, 2014 at 2:58 PM, Andrew Gerrand <adg@golang.org> wrote: > "godoc code.google.com/p/go.tools/cmd/vet" also provides these same docs. > > Since we need to invoke vet with "go tool vet" to use these flags, it seems > logical that the docs should be in vet's doc.go file. > > This change makes sense to me, and I don't really have any other > suggestions. > > > On 12 February 2014 02:44, Rob Pike <r@golang.org> wrote: >> >> Yes, I know what it is. I'm asking where the information belongs. It >> feels fragile and a bit odd to me to have the rich documentation like >> this far from the program that it describes. >> >> -rob >> >> >> On Mon, Feb 10, 2014 at 10:55 PM, Andrew Gerrand <adg@golang.org> wrote: >> > This is the vet tool's doc.go (nothing to do with cmd/go) as viewable >> > here: >> > >> > http://godoc.org/code.google.com/p/go.tools/cmd/vet >> > >> > But we could put these docs into the vet tool's command-line help as >> > well. >> > >> > >> > On 11 February 2014 17:52, <r@golang.org> wrote: >> >> >> >> I wonder if this is such a good idea. Should this be in the vet binary >> >> itself? It's reasonable to run it outside the go tool; it seems odd >> >> (but >> >> perhaps justifiable) to have all the documentation be in a different >> >> program altogether, far away and likely to become outdated. >> >> >> >> In short, this could be >> >> >> >> for details, run go tool vet --help >> >> >> >> and then help in the vet program could actually say something. >> >> >> >> >> >> It's a question. I'm seeking opinions. >> >> >> >> >> >> >> >> https://codereview.appspot.com/61480044/ >> > >> > > >
Sign in to reply to this message.
https://codereview.appspot.com/61480044/diff/1/cmd/vet/doc.go File cmd/vet/doc.go (right): https://codereview.appspot.com/61480044/diff/1/cmd/vet/doc.go#newcode28 cmd/vet/doc.go:28: Printf family i like the numbers because the break up the flow and make it easier to separate subtitle from content. https://codereview.appspot.com/61480044/diff/1/cmd/vet/doc.go#newcode119 cmd/vet/doc.go:119: These flags configure the behavior of vet: -shadow is missing.
Sign in to reply to this message.
Hello r@golang.org (cc: golang-codereviews@googlegroups.com), Please take another look.
Sign in to reply to this message.
LGTM but do the renumbering first. https://codereview.appspot.com/61480044/diff/20001/cmd/vet/doc.go File cmd/vet/doc.go (right): https://codereview.appspot.com/61480044/diff/20001/cmd/vet/doc.go#newcode28 cmd/vet/doc.go:28: Printf family isn't this 1.?
Sign in to reply to this message.
*** Submitted as https://code.google.com/p/go/source/detail?r=698202246815&repo=tools *** go.tools/cmd/vet: add stable checks to doc.go These are the simplest possible descriptions of each command. They may be fleshed out later. Fixes issue 7298. LGTM=r R=r CC=golang-codereviews https://codereview.appspot.com/61480044 https://codereview.appspot.com/61480044/diff/20001/cmd/vet/doc.go File cmd/vet/doc.go (right): https://codereview.appspot.com/61480044/diff/20001/cmd/vet/doc.go#newcode28 cmd/vet/doc.go:28: Printf family On 2014/02/12 23:46:09, r wrote: > isn't this 1.? Done.
Sign in to reply to this message.
|
