Change https://golang.org/cl/253537 mentions this issue: runtime: update docs for GOMAXPROCS

The number of logical CPUs on the local machine can be queried with NumCPU. This call will go away when the scheduler improves.

Neither of those statements is incorrect or outdated.

The first statement is correct. Not entirely sure why it is in the GOMAXPROCS docs, though. It suggests the maximum reasonable argument, perhaps? It could be worded better.

It's always been a desire to have the scheduler adjust its processor use automatically, so that GOMAXPROCS would not be necessary. (Not that I think we will ever get there, but one less knob would be great if we can figure out how to do it.)

@randall77, thank you for your comment. The issue that I was trying to describe is located in the description of the method which gives an example of how to use it. I remember the time when we had to explicitly call it in order to make async code work, now this call can be omitted and it simply makes no sense calling it with an argument NumCPU by default. That is why I think it is important to update this part of the description.
Now about the scheduler part. I can understand the idea to completely remove GOMAXPROCS call in the future, but is it gonna happen someday? Probably. Should this information stay in the method description till that moment? Not sure.

The issue that I was trying to describe is located in the description of the method which gives an example of how to use it.

Where is that? It's not in the GOMAXPROCS doc.

I remember the time when we had to explicitly call it in order to make async code work, now this call can be omitted and it simply makes no sense calling it with an argument NumCPU by default.

You're right that a call to runtime.GOMAXPROCS(runtime.NumCPU()) can be omitted. (At least, on startup. It makes sense to do runtime.GOMAXPROCS(runtime.NumCPU()) if you previously called runtime.GOMAXPROCS with some other argument earlier in the program.)

But there's a big difference between "can be omitted" and "must be omitted". It's not hurting anything to leave it there.

To be clear, I'm happy with changing the description to say that GOMAXPROCS defaults to NumCPU.

Should this information stay in the method description till that moment? Not sure.

I'm not sure either. But someone at some point decided this was worth saying. I'm willing to give them the benefit of the doubt, if for no other reason than it introduces some hysteresis to doc changes so we don't keep changing our minds about it every release.

Where is that? It's not in the GOMAXPROCS doc.

I meant to say that you can interpret these doc comments like an example of how to use it.

But there's a big difference between "can be omitted" and "must be omitted". It's not hurting anything to leave it there.

I'd say that unnecessary call of the code instructions that makes no changes is already hurting us if we want to make things as good as we can.

The whole point I'm trying to make is that by reading current docs for this function you can misunderstand the usage of it. For me, it happened while I was reviewing the code. I checked the docs to make sure that I correctly remember that there was a change that runtime.GOMAXPROCS(runtime.NumCPU()) for the current go version is the default behavior and what I've found is that The number of logical CPUs on the local machine can be queried with NumCPU. it's definitely not what I was looking for. That's why I had to search for the release notes to make sure that I'm not imagining things.