code review 9144050: runtime/race: improve public documentation

runtime/race: improve public documentation
Move the documentation from race.go to doc.go, because
race.go uses +build race, so it's not normally parsed by go doc.
Rephrase the documentation for end users, provide link to race
detector manual.
Fixes issue 5444.

[dvyukov, 2013-05-12 11:11:52]

Hello golang-dev@googlegroups.com,

I'd like you to review this change to
https://dvyukov%40google.com@code.google.com/p/go/

[minux1, 2013-05-12 16:15:18]

description: s/documentatino/documentation/.

should we also fix cmd/godoc?

[minux1, 2013-05-12 16:16:40]

the change itself LGTM.

[adg, 2013-05-13 00:32:31]

LGTM

I'll also apply this to the release branch.

[r, 2013-05-13 01:28:20]

LGTM

[dvyukov, 2013-05-13 06:24:51]

On 2013/05/12 16:15:18, minux wrote:
> description: s/documentatino/documentation/.

done
 
> should we also fix cmd/godoc?

what exactly do you mean?
I think it's bad idea to parse all files. There can be "+build" (disabled) files
and lots of duplicates and irrelevant functions for e.g. syscall.

[dvyukov, 2013-05-13 06:28:32]

*** Submitted as https://code.google.com/p/go/source/detail?r=d29da2ced72b ***

runtime/race: improve public documentation
Move the documentation from race.go to doc.go, because
race.go uses +build race, so it's not normally parsed by go doc.
Rephrase the documentation for end users, provide link to race
detector manual.
Fixes issue 5444.

R=golang-dev, minux.ma, adg, r
CC=golang-dev
https://codereview.appspot.com/9144050

[minux1, 2013-05-13 07:56:38]

On Mon, May 13, 2013 at 2:24 PM, <dvyukov@google.com> wrote:

> > should we also fix cmd/godoc?
> what exactly do you mean?
> I think it's bad idea to parse all files. There can be "+build"
> (disabled) files and lots of duplicates and irrelevant functions for
> e.g. syscall.
>
sorry, i should have been more specific here.

do you think it's a bug of godoc to regard runtime/race as a command prior
to this CL?
(there is no package main in runtime/race)

$ godoc runtime 2>/dev/null |head -1
PACKAGE DOCUMENTATION
$ godoc runtime/race 2>/dev/null |head -1
COMMAND DOCUMENTATION

[dvyukov, 2013-05-13 08:18:17]

On Mon, May 13, 2013 at 11:56 AM, minux <minux.ma@gmail.com> wrote:
>
> On Mon, May 13, 2013 at 2:24 PM, <dvyukov@google.com> wrote:
>>
>> > should we also fix cmd/godoc?
>> what exactly do you mean?
>> I think it's bad idea to parse all files. There can be "+build"
>> (disabled) files and lots of duplicates and irrelevant functions for
>> e.g. syscall.
>
> sorry, i should have been more specific here.
>
> do you think it's a bug of godoc to regard runtime/race as a command prior
> to this CL?
> (there is no package main in runtime/race)
>
> $ godoc runtime 2>/dev/null |head -1
> PACKAGE DOCUMENTATION
> $ godoc runtime/race 2>/dev/null |head -1
> COMMAND DOCUMENTATION

Probably it's a bug, I don't know.

[minux1, 2013-05-13 08:56:43]

On Mon, May 13, 2013 at 4:18 PM, Dmitry Vyukov <dvyukov@google.com> wrote:

> On Mon, May 13, 2013 at 11:56 AM, minux <minux.ma@gmail.com> wrote:
> >
> > On Mon, May 13, 2013 at 2:24 PM, <dvyukov@google.com> wrote:
> >>
> >> > should we also fix cmd/godoc?
> >> what exactly do you mean?
> >> I think it's bad idea to parse all files. There can be "+build"
> >> (disabled) files and lots of duplicates and irrelevant functions for
> >> e.g. syscall.
> >
> > sorry, i should have been more specific here.
> >
> > do you think it's a bug of godoc to regard runtime/race as a command
> prior
> > to this CL?
> > (there is no package main in runtime/race)
> >
> > $ godoc runtime 2>/dev/null |head -1
> > PACKAGE DOCUMENTATION
> > $ godoc runtime/race 2>/dev/null |head -1
> > COMMAND DOCUMENTATION
>
> Probably it's a bug, I don't know.
>
Ah, it's a special case for the tools written in C,
from cmd/godoc/godoc.go:
        // collect package files
        pkgname := pkginfo.Name
        pkgfiles := append(pkginfo.GoFiles, pkginfo.CgoFiles...)
        if len(pkgfiles) == 0 {
                // Commands written in C have no .go files in the build.
                // Instead, documentation may be found in an ignored file.
                // The file may be ignored via an explicit +build ignore
                // constraint (recommended), or by defining the package
                // documentation (historic).
                pkgname = "main" // assume package main since pkginfo.Name
== ""
                pkgfiles = pkginfo.IgnoredGoFiles
        }

so any package without Go source is treated as a command.