runtime/pprof: document the requirement to wait to capture any CPU profile samples

[rakyll]

Package's godoc example starts the CPU profiling and defers pprof.StopCPUProfile, but it fails to document that the function need to spend sometime before returning in order for any samples to be collected. We might want to add a time.Sleep to make it more obvious and document it throughly that time is required to collect samples.

if err := pprof.StartCPUProfile(f); err != nil {
    log.Fatal("could not start CPU profile: ", err)
}
defer pprof.StopCPUProfile()

[ALTree]

IMHO a call to time.Sleep is not the right thing to add if the message you want to give is "and then the code that does the work starts". That would be quite confusing ("do I have to call Sleep to make the profiler work?", I'd ask myself).

Right now there's a line with three dots after the defer:

...

I agree that's confusing. It could be replaced with a go comment that explicitly explains that after setting up the profiler in the main function, you'll need to call the actual code (the one that does the work you're going to profile).

[bradfitz]

The example already contains the line:

    ...

Hah, @ALTree just said the same thing.

Let's just add another bit at the bottom:

    // ... rest of program ...

[rakyll]

Sorry, what I meant is having a reference of starting, sleeping, stoping in a different goroutine to give an idea this is how you profile for x seconds. I see users copy/pasting this code without much questioning and fail to collect any samples.

Improving the ... comment would also work.

[gopherbot]

CL https://golang.org/cl/36430 mentions this issue.