Comment 1:

Perhaps we should have a bit more documentation about the GC behaviour--I'm not sure. 
But I'm pretty sure that runtime.GC is not the right place to document it.

Labels changed: added repo-main, release-none, documentation.

Status changed to Thinking.

Comment 2:

Would it be possible to hear your reasoning about why is this a wrong place? Mine
thoughts are:
There may be more, yet I immediately see two ways to think about where the clarification
belongs.
If the purpose of such clarification is to generally educate and explain concepts as
well as intricacies of the Go garbage collection process, then documenting it at the
function level is wrong as far as I am concerned.
On the other hand, if the purpose is to set clear expectations of the specific function
intended and side effects, then it seems to be a very Go thing to put it right there by
the function in the code. #amiright?
The depth of the clarification may reflect the chosen purpose.

Comment 3:

Would it be possible to hear your reasoning about why is this a wrong place? Mine
thoughts are:
There may be more, yet I immediately see two ways to think about where the clarification
belongs.
If the purpose of such clarification is to generally educate and explain concepts as
well as intricacies of the Go garbage collection process, then documenting it at the
function level is wrong as far as I am concerned.
On the other hand, if the purpose is to set clear expectations of the specific function
intended and side effects, then it seems to be a very Go thing to put it right there by
the function in the code. #amiright?
Depth of the clarification may reflect its chosen purpose.

Comment 4:

The documentation of the function should describe not only what it does today, but also
what we promise that it will do for while Go 1 is still valid.  Documentation is not
merely a description, it's also a contract.  We don't want to promise that the GC is a
mark and sweep.  We don't want to promise anything about how or whether we return memory
to the system.  Those are implementation details.

Comment 5:

Thank you very much for answering the questions in detail.
I understand, that in-code documentation sets the scope of user expectations over time.
What I feel is the contract in this case is too restrictive to be useful. If garbage
collection concept is not stable internally throughout Go 1 then this contract
effectively promises nothing. It is not clear then, why the function was made public -
or documented at all. Or, if the expectation is to have no "user-land" calls to this
function, should _that_ be documented?
What I would like to have is an assurance, that a freezing part of garbage collection
will be over by the time runtime.GC() returns - that is my reason to call the function.
Such assurance may not be possible at this stage by the sound of it. Do I understand
this correctly?
I am not sure I am clear about the criteria of separating an implementation detail vs.
declared functionality - except for this:
If the intent of "GC runs a garbage collection" description is to refer to an abstract
notion of "garbage collection" described somewhere else, then it kinda makes sense, if
that "somewhere else" is findable (to your point in the first comment). Currently,
Google search "garbage collect site:golang.org" returns no meaningful reference to what
Golang garbage collection means in details.
The bottom line for me in this issue is that I like Go documentation for that it has the
necessary information to proceed with coding in most cases. Not in case of runtine.GC()
- and I am not sure how to fix it. Documenting it externally seems to reduce the "Code
docs contain it all" quality.

Comment 6 by voidlogic7:

IMHO all that should change here is:
"GC runs a garbage collection." to:
"GC optionally runs a garbage collection at the discretion of the runtime
implementation."

Comment 7:

i think we do need to provide the guarantee that runtime.GC() does
trigger a GC (i.e. it's not optional).
I also think the the current docs is good enough.

Comment 8:

OK, I have to admit now I see this issue originally written with a relatively vague
understanding of the problem. With (hopefully) somewhat more specific view of the domain
here is my current list of possible "contractual" promises behind the GC() call:
1. No promise regarding functionality whatsoever.
2. No promise regarding instance freeze whatsoever.
3. After GC() return freed application memory will be available for the OS to collect at
it's own pace.
4. If something to be done, it will be over by the time GC() returns.
5. If there will be a freeze, it will be over by the time GC() returns. A specific
runtime implementation should document if a behavior is different.
6. There is no other freeze initiated except for when something calls GC() either in by
user code or the runtime library. A specific runtime implementation should document if a
behavior is different.
7. Runtime calls to GC() are controlled by the feature ___ (fill the blank). A specific
runtime implementation should document if a behavior is different.
Note, I am avoiding to mention implementation details in promises except for freeze
boundaries expectations. The indeterminate timing side effect of a freeze feels
impactful enough to request it to be somewhat documented. A side effect is not an
implementation detail, isn't it?
In addition to the promises themselves, there are longevity expectations (horizons),
given the still-flexible status of memory management in Go. So here are my candidates:
A. May change at any time
B. May never change
C. Will not change until the next minor release
D. Will not change until the next major release
E. Will not change until drastic changes in Go gc architecture
I take it as granted that these lists are incomplete.
The current code (and embedded doc) promises seem to be 1, 2, 3, A, B. Which makes me
wonder, why GC() is made a public method at all? My guess is that other packages, like
benchmarks, actually do need some of promises above, and do need public access to the
call. So there are promises beyond 3 and horizons beyond b which are known to a group of
developers, just not documented to the rest of the public. If one takes time to read the
code, than may answer promise questions, yet this will not clarify horizons. If one
searches forums they may get a feeling of a horizon for a specific promise. Both take
considerable time. It is hard to see this part of documentation as an efficient and
effective developer-to-developer communication.
As Ian caught me red-handed :D I would like to have this contract changed. My
preferences are promises 5, 6, and 7 with the E horizon. Logic being that if gc changes
dramatically, the consumers will want to adjust for the new behavior anyhow.
I understand the beauty of programming for an unpredictable environment. I understand
and experienced that this approach tends to produce more reliable systems. However, it
is effective as an approach when a developer strike a fine balance in their trade-offs.
I think we can improve this communication to have a better understanding of behavior
determinism inside our executables after build time. I also think it is reasonable that
some important documentation to be delegated to and request from runtime implementations.

Current documentation for the function states:

GC runs a garbage collection and blocks the caller until the garbage collection is complete. It may also block the entire program.

@didenko, It looks to me that staying away from false promises in documentation is the right approach. Some facts from 4 years ago are not valid anymore. So it is good that we have not added any promises there. Also the general documentation for the runtime package have improved a lot since that time: https://golang.org/pkg/runtime/

Do you think that we can close this issue?

@ysmolsky I do not see a reason to keep the ticket open now. As a bit of feedback: it would be great to avoid judgemental (and so confrontational) statements like "false promises". No one in this issue intended to introduce misleading documentation - neither at that point in time nor as a promise.

I am sorry that it sounded that way. What I meant: it is good that we have not added more documentation there because some things that were true 4 years ago are not true anymore. Thanks for the feedback and response.

@didenko Thanks for pointing out that "false promises" sounds judgemental and confrontational. I would say that in English it is not confrontational; it means something like "a good intention that turned out to be a mistake." Personally I'll try to be aware in the future of how it sounds to others.