[gtkmm/gtkmm-3-24] Gtk::Application, Window: Improve some documentation

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 27eb4f8988f8fcb58c44e7d4855666ae67f2ed0a
Author: Kjell Ahlstedt <kjellahlstedt gmail com>
Date:   Thu Nov 14 16:39:37 2019 +0100

    Gtk::Application, Window: Improve some documentation
    
    Improve the description of Application::add_window() and
    Window::set_application(), making it clear that they differ as to what
    happens when a window is hidden.
    
    Fixes #56

 gtk/src/application.hg | 11 ++++++++---
 gtk/src/window.hg      | 17 +++++++++++++++++
 2 files changed, 25 insertions(+), 3 deletions(-)
---
diff --git a/gtk/src/application.hg b/gtk/src/application.hg
index d89d6bc3..9c1295a6 100644
--- a/gtk/src/application.hg
+++ b/gtk/src/application.hg
@@ -207,13 +207,18 @@ public:
 #m4 _CONVERSION(`GList*',`std::vector<const Window*>',`Glib::ListHandler<const Window*>::list_to_vector($3, 
Glib::OWNERSHIP_NONE)')
   _WRAP_METHOD(std::vector<const Window*> get_windows() const, gtk_application_get_windows)
 
-  //Concerning the note on quit(), see https://bugzilla.gnome.org/show_bug.cgi?id=731126
+  // Concerning the note on quit(), see https://bugzilla.gnome.org/show_bug.cgi?id=731126
+  // Concerning the return from run() on hidden windows, see
+  // https://bugzilla.gnome.org/show_bug.cgi?id=639931
   /** Adds a window to the Gtk::Application.
    *
    * If all the windows managed by Gtk::Application are closed (hidden) or
-   * removed from the application then the call to run() will return.
+   * removed from the application then the call to run() will return,
+   * unless Gio::Application::hold() has been called.
    *
-   * This call is equivalent to calling Gtk::Window::set_application().
+   * This call is equivalent to calling Gtk::Window::set_application(), except
+   * that run() does not return when a window added with Gtk::Window::set_application()
+   * is closed (hidden).
    *
    * Normally, the connection between the application and the window
    * will remain until the window is closed (hidden) or destroyed, but you can explicitly
diff --git a/gtk/src/window.hg b/gtk/src/window.hg
index 9374d406..f68e7127 100644
--- a/gtk/src/window.hg
+++ b/gtk/src/window.hg
@@ -373,6 +373,23 @@ dnl
   _WRAP_METHOD(Glib::RefPtr<Application> get_application(), gtk_window_get_application, refreturn)
   _WRAP_METHOD(Glib::RefPtr<const Application> get_application() const, gtk_window_get_application, 
refreturn)
 
+  /** Sets the Gtk::Application associated with the window.
+   *
+   * The application will be kept alive for at least as long as it has any windows
+   * associated with it. (See Gio::Application::hold() for a way to keep it alive
+   * without windows.)
+   *
+   * Normally, the connection between the application and the window will remain
+   * until the window is destroyed, but you can explicitly remove it by
+   * calling unset_application().
+   *
+   * This is equivalent to calling Gtk::Application::remove_window() and/or
+   * Gtk::Application::add_window() on the old/new applications as relevant,
+   * except that the connection between the application and a window added with
+   * Gtk::Application::add_window() is removed when the window is closed (hidden).
+   *
+   * @param application A Gtk::Application.
+   */
   _WRAP_METHOD(void set_application(const Glib::RefPtr<Application>& application), 
gtk_window_set_application)
 
   /** Unsets the Application associated with the window.