docs: Clearly document the behavior of ee.once().
Checklist
-
documentation is changed or added -
the commit message follows commit guidelines
Affected core subsystem(s)
doc
Description of change
Addresses #5566 (closed). The ee.once()
function is currently documented as
invoking the listener, and then removing it when the event is
triggered. However, this is not really the case. The listener is removed
and then invoked. This only matters in a narrow set of use cases, but
when it matters, it matters that the docs are correct.
See the issue (#5566 (closed)) for a discussion on why the code has not been modified to match the documentation, but instead the documentation has been modified to match the code.