Refresh Scope documentation could be improved

[jhyot]

In my opinion the documentation of Refresh Scope is lacking some relevant details, listed below.

How to trigger a refresh programmatically inside the application?

The docs talk about the RefreshScope bean and its refreshAll() method. But there seems to be also a ContextRefresher bean registered in the context, that seems to refresh the scope and the environment together. Can we use that? It is not mentioned in the docs.

Also there seems to be a listener for a RefreshEvent that then triggers the ContextRefresher. This is also not mentioned.

What is the mechanism of the application context refresh?

The mechanism for the refresh is not detailed. Are there any important performance considerations (or similar)? I found a blog article that illustrates a situation where the refresh blocks calls to the beans for a long time: https://medium.com/analytics-vidhya/spring-cloud-config-server-and-good-practice-of-refresh-scope-usage-ef65d0fee379

Is this still the case? How does this actually work? If true, then it may be important to note in the doc that @RefreshScope beans should be as simple as possible, or some similar hint.

Lazy initialization of beans

The docs mention that refresh scope beans are lazily initialized. But in the RefreshScope code I also found a flag eager (which seems to be always true), which seems to control whether refresh scope beans are initialized eagerly when the application first starts. Should that be documented, otherwise people are under the impression that even at the start the beans are lazily initialized?