diff --git a/ChangeLog b/ChangeLog
index 81b146460..b4eac7363 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,7 @@
 2004-11-01  Matthias Clasen  <mclasen@redhat.com>
 
+	* glib/goption.c: Documentation updates.
+
 	Handle conflicts between options in different groups. (#156808)
 	
 	* glib/goption.c (g_option_context_parse): When a long option does not
diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10
index 81b146460..b4eac7363 100644
--- a/ChangeLog.pre-2-10
+++ b/ChangeLog.pre-2-10
@@ -1,5 +1,7 @@
 2004-11-01  Matthias Clasen  <mclasen@redhat.com>
 
+	* glib/goption.c: Documentation updates.
+
 	Handle conflicts between options in different groups. (#156808)
 	
 	* glib/goption.c (g_option_context_parse): When a long option does not
diff --git a/ChangeLog.pre-2-12 b/ChangeLog.pre-2-12
index 81b146460..b4eac7363 100644
--- a/ChangeLog.pre-2-12
+++ b/ChangeLog.pre-2-12
@@ -1,5 +1,7 @@
 2004-11-01  Matthias Clasen  <mclasen@redhat.com>
 
+	* glib/goption.c: Documentation updates.
+
 	Handle conflicts between options in different groups. (#156808)
 	
 	* glib/goption.c (g_option_context_parse): When a long option does not
diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6
index 81b146460..b4eac7363 100644
--- a/ChangeLog.pre-2-6
+++ b/ChangeLog.pre-2-6
@@ -1,5 +1,7 @@
 2004-11-01  Matthias Clasen  <mclasen@redhat.com>
 
+	* glib/goption.c: Documentation updates.
+
 	Handle conflicts between options in different groups. (#156808)
 	
 	* glib/goption.c (g_option_context_parse): When a long option does not
diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8
index 81b146460..b4eac7363 100644
--- a/ChangeLog.pre-2-8
+++ b/ChangeLog.pre-2-8
@@ -1,5 +1,7 @@
 2004-11-01  Matthias Clasen  <mclasen@redhat.com>
 
+	* glib/goption.c: Documentation updates.
+
 	Handle conflicts between options in different groups. (#156808)
 	
 	* glib/goption.c (g_option_context_parse): When a long option does not
diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 6b52be4e4..4543059ee 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,7 @@
+2004-11-01  Matthias Clasen  <mclasen@redhat.com>
+
+	* glib/tmpl/option.sgml: Updates
+
 2004-10-31  Matthias Clasen  <mclasen@redhat.com>
 
 	* glib/tmpl/windows.sgml: Document G_WIN32_IS_NT_BASED,
diff --git a/docs/reference/glib/tmpl/option.sgml b/docs/reference/glib/tmpl/option.sgml
index 2a92f7a7b..2f8956845 100644
--- a/docs/reference/glib/tmpl/option.sgml
+++ b/docs/reference/glib/tmpl/option.sgml
@@ -53,7 +53,7 @@ and write a text similar to the one shown in the following example to stdout.
 
 <informalexample><screen>
 Usage:
-  testtreemodel [OPTION...]
+  testtreemodel [OPTION...] - test tree model performance
 
 Help Options:
   --help                   Show help options
@@ -109,7 +109,7 @@ main (int argc, char *argv[])
 {
   GError *error = NULL;
 
-  context = g_option_context_new ("[OPTION...]");
+  context = g_option_context_new ("- test tree model performance");
   g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE);
   g_option_context_add_group (context, gtk_get_option_group (TRUE));
   g_option_context_parse (context, &amp;argc, &amp;argv, &amp;error);
@@ -291,7 +291,10 @@ g_option_context_add_main_entries() or g_option_group_add_entries().
 
 @long_name: The long name of an option can be used to specify it
   in a commandline as --<replaceable>long_name</replaceable>. Every
-  option must have a long name.
+  option must have a long name. To resolve conflicts if multiple
+  option groups contain the same long name, it is also possible to
+  specify the option as 
+  --<replaceable>groupname</replaceable>-<replaceable>long_name</replaceable>.
 @short_name: If an option has a short name, it can be specified
   -<replaceable>short_name</replaceable> in a commandline.
 @flags: Flags from #GOptionEntryFlags.
diff --git a/glib/goption.c b/glib/goption.c
index 99ad65c11..960a09738 100644
--- a/glib/goption.c
+++ b/glib/goption.c
@@ -116,8 +116,9 @@ g_option_error_quark (void)
 
 /**
  * g_option_context_new:
- * @parameter_string: the parameter string to be used in 
- *    <option>--help</option> output.
+ * @parameter_string: a string which is displayed in
+ *    the first line of <option>--help</option> output, after 
+ *    <literal><replaceable>programname</replaceable> [OPTION...]</literal>
  *
  * Creates a new option context. 
  *