[gtkmm] Update documentation of Gtk::Dialog::run()

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 613b122d26e77f22142c1c61056c421d79029658
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Thu May 1 14:57:01 2014 +0200

    Update documentation of Gtk::Dialog::run()
    
    * gtk/src/dialog.hg: Add documentation of Gtk::Dialog::run(), similar to
    the gtk+ documentation, except for the code snippet.
    * gtk/src/gtk_docs_override.xml: Remove documentation of gtk_dialog_run().

 gtk/src/dialog.hg             |   45 +++++++++++++++++++++++++++++++++++++++++
 gtk/src/gtk_docs_override.xml |   34 -------------------------------
 2 files changed, 45 insertions(+), 34 deletions(-)
---
diff --git a/gtk/src/dialog.hg b/gtk/src/dialog.hg
index da8fdd3..20d2988 100644
--- a/gtk/src/dialog.hg
+++ b/gtk/src/dialog.hg
@@ -117,6 +117,51 @@ _DEPRECATE_IFDEF_START
 _DEPRECATE_IFDEF_END
 
   _WRAP_METHOD(void response(int response_id), gtk_dialog_response)
+
+  /** Blocks in a recursive main loop until the dialog either emits the
+   * Gtk::Dialog::signal_response() signal, or is destroyed. If the dialog is
+   * destroyed during the call to run(), run() returns
+   * Gtk::RESPONSE_NONE. Otherwise, it returns the response ID from the
+   * signal_response() signal emission.
+   *
+   * Before entering the recursive main loop, run() calls
+   * Gtk::Widget::show() on the dialog for you. Note that you still
+   * need to show any children of the dialog yourself.
+   *
+   * During run(), the default behavior of Gtk::Widget::signal_delete_event()
+   * is disabled; if the dialog receives the signal_delete_event() signal, it will not be
+   * destroyed as windows usually are, and run() will return
+   * Gtk::RESPONSE_DELETE_EVENT. Also, during run() the dialog
+   * will be modal. You can force run() to return at any time by
+   * calling response() to emit the signal_response() signal. Destroying
+   * the dialog during run() is a very bad idea, because your
+   * post-run code won’t know whether the dialog was destroyed or not.
+   *
+   * After run() returns, you are responsible for hiding or
+   * destroying the dialog if you wish to do so.
+   *
+   * Typical usage of this function might be:
+   * @code
+   * int result = dialog.run();
+   * switch (result)
+   * {
+   * case Gtk::RESPONSE_ACCEPT:
+   *   do_application_specific_something();
+   *   break;
+   * default:
+   *   do_nothing_since_dialog_was_cancelled();
+   *   break;
+   * }
+   * @endcode
+   *
+   * Note that even though the recursive main loop gives the effect of a
+   * modal dialog (it prevents the user from interacting with other
+   * windows in the same window group while the dialog is run), callbacks
+   * such as timeouts, IO channel watches, DnD drops, etc, will
+   * be triggered during a run() call.
+   *
+   * @return Response ID.
+   */
   _WRAP_METHOD(int run(), gtk_dialog_run)
 
   // This previously returned an HButtonBox*, which broke on Maemo Fremantle.
diff --git a/gtk/src/gtk_docs_override.xml b/gtk/src/gtk_docs_override.xml
index e1f074a..36f8737 100644
--- a/gtk/src/gtk_docs_override.xml
+++ b/gtk/src/gtk_docs_override.xml
@@ -108,40 +108,6 @@ override the defaults. The returned array will be empty if
 </return>
 </function>
 
-
-<function name="gtk_dialog_run">
-<description>
-Blocks in a recursive main loop until the @dialog emits the
-response signal. It returns the response ID from the &quot;response&quot; signal emission.
-Before entering the recursive main loop, gtk_dialog_run() calls
-Gtk::Widget::show() on the dialog for you. Note that you still
-need to show any children of the dialog yourself.
-
-If the dialog receives &quot;delete_event&quot;,  Gtk::Dialog::run() will return
-#GTK_RESPONSE_DELETE_EVENT. Also, during Gtk::Dialog::run() the dialog will be
-modal. You can force Gtk::Dialog::run() to return at any time by
-calling Gtk::Dialog::response() to emit the &quot;response&quot;
-signal.
-
-After Gtk::Dialog::run() returns, you are responsible for hiding or
-destroying the dialog if you wish to do so.
-
-Typical usage of this function might be:
-&amp;lt;informalexample&amp;gt;&amp;lt;programlisting&amp;gt;
-int result = dialog.run();
-switch (result)
-{
-case Gtk::RESPONSE_ACCEPT:
-  do_application_specific_something ();
-  break;
-default:
-  do_nothing_since_dialog_was_cancelled ();
-  break;
-}
-&amp;lt;/programlisting&amp;gt;&amp;lt;/informalexample&amp;gt;
-</description>
-</function>
-
 <function name="gtk_accel_label_get_accel_width">
 <description>
 Gets the width needed to display this accelerator label. This is used by menus to align all of the 
Gtk::MenuItem widgets, and shouldn't be needed by applications.