[gtkmm] Main: Improve the documentation.

[Murray Cumming <murrayc src gnome org>]

commit d8aaddd11989c4eeaa533b2cb1ca189f9b97e0bc
Author: Murray Cumming <murrayc murrayc com>
Date:   Mon Mar 7 13:31:35 2011 +0100

    Main: Improve the documentation.
    
    * gtk/src/main.hg: Improve the overview documentation and the constructors'
    documentation.

 ChangeLog       |    7 +++++++
 gtk/src/main.hg |   52 ++++++++++++++++++++++++++++++++++++----------------
 2 files changed, 43 insertions(+), 16 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index d8bf684..43cc79a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,12 @@
 2011-03-07  Murray Cumming  <murrayc murrayc com>
 
+	Main: Improve the documentation.
+
+	* gtk/src/main.hg: Improve the overview documentation and the constructors' 
+	documentation.
+
+2011-03-07  Murray Cumming  <murrayc murrayc com>
+
 	Gtk::Main: Add a constructor with no argc and argv.
 
 	* gtk/src/main.[hg|ccg]: Main: Add a public constructor with no argc/argv 
diff --git a/gtk/src/main.hg b/gtk/src/main.hg
index c49d000..e5d4bce 100644
--- a/gtk/src/main.hg
+++ b/gtk/src/main.hg
@@ -55,26 +55,25 @@ protected:
 
 //**********************************************************************
 
-/** Main application class
+/** Main application class.
  * Every application must have one of these objects.
- * It may not be global and must be the first Gtk object created.
+ * It may not be global and must be the first gtkmm object created.
  * It is a singleton so declaring more than one will simply access the first
  * created.
  *
- * Normal use of this class is in the main() function to give argc and argv
- * to the gtk initialization. Widgets can use Gtk::Main::quit()
- * to exit from the application.
+ * You would normally use this class in your main() function to initialize gtkmm 
+ * and optionally to give argc and argv to the GTK+ initialization. 
+ * After calling Gtk::Main::run(), you may use Gtk::Main::quit() to exit from 
+ * the application, or just pass your main window to run(), to make run() 
+ * return when that window closes.
  *
- * The internals of the widget have been disguised as signals
- * so that the user can easily connect using the same methods
- * used throughout the widget interface.
- *
- * Minimal gtkmm application is something like this:
+ * A minimal gtkmm application would be something like this:
  * @code
- * int main(int argc, char *argv[]) {
- *     Gtk::Main kit(argc, argv);
- *     ... create some widgets ...
- *     kit.run();
+ * int main(int argc, char *argv[])
+ * {
+ *   Gtk::Main kit(argc, argv);
+ *   ... create some widgets and windows...
+ *   kit.run(window);
  * }
  * @endcode
  */
@@ -112,13 +111,34 @@ public:
    * pointers to them might change.  This makes it possible to create your
    * own argv of string literals, which have the type 'const char[]' in
    * standard C++.  (You might need to use const_cast<>, though.)
+   *
+   * @param argc a pointer to the number of command line arguments.
+   * @param argv a pointer to the array of command line arguments.
+   * @param set_locale Passing false prevents GTK+ from automatically calling 
+   * setlocale(LC_ALL, ""). You would want to pass false if you wanted to set 
+   * the locale for your program to something other than the user's locale, or 
+   * if you wanted to set different values for different locale categories.
    */
   Main(int* argc, char*** argv, bool set_locale = true);
 
-  /// See Main(int* argc, char*** argv, bool set_locale).
+  /** Scans the argument vector, and strips off all parameters known to GTK+.
+   * Your application may then handle the remaining arguments.
+   *
+   * @param argc a reference to the number of command line arguments.
+   * @param argv a reference to the array of command line arguments.
+   * @param set_locale Passing false prevents GTK+ from automatically calling 
+   * setlocale(LC_ALL, ""). You would want to pass false if you wanted to set 
+   * the locale for your program to something other than the user's locale, or 
+   * if you wanted to set different values for different locale categories.
+   */
   Main(int& argc, char**& argv, bool set_locale = true);
   
-  /**
+  /** Initialization without command-line arguments.
+   *
+   * @param set_locale Passing false prevents GTK+ from automatically calling 
+   * setlocale(LC_ALL, ""). You would want to pass false if you wanted to set 
+   * the locale for your program to something other than the user's locale, or 
+   * if you wanted to set different values for different locale categories.
    */
   explicit Main(bool set_locale = true);