[glib/mcatanzaro/gresolver-reload: 9/12] gresolver: improve documentation of reload signal

[Michael Catanzaro <mcatanzaro src gnome org>]

commit 68468e7a46d3b44455c7a4050ca331c47dbae7aa
Author: Michael Catanzaro <mcatanzaro redhat com>
Date:   Mon Nov 22 15:08:03 2021 -0600

    gresolver: improve documentation of reload signal

 gio/gresolver.c | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)
---
diff --git a/gio/gresolver.c b/gio/gresolver.c
index cd5445a65..ecc40e87d 100644
--- a/gio/gresolver.c
+++ b/gio/gresolver.c
@@ -160,9 +160,17 @@ g_resolver_class_init (GResolverClass *resolver_class)
    * GResolver::reload:
    * @resolver: a #GResolver
    *
-   * Emitted when the resolver notices that the system resolver
-   * configuration has changed.
-   **/
+   * On UNIX systems, this signal is emitted when `/etc/resolv.conf` is
+   * changed. If you are building a DNS cache on top of #GResolver, you
+   * can use this signal as a hint to refresh the cache, which is useful
+   * on systems that lack a modern local caching DNS resolver like
+   * systemd-resolved or dnsmasq. Be aware that on modern systems with
+   * local caching resolvers, `/etc/resolv.conf` will most likely never be
+   * updated when DNS configuration changes, and this signal will never
+   * be emitted.
+   *
+   * On Windows, this signal is never emitted.
+   */
   signals[RELOAD] =
     g_signal_new (I_("reload"),
                  G_TYPE_RESOLVER,