diff --git a/ChangeLog b/ChangeLog
index 3ec12a7367..4b68cb4a65 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2009-01-15  Murray Cumming  <murrayc@murrayc.com>
+
+	* gtk/gtkimcontext.c: documentation description: Mention the various 
+	properties and the environment variable, with links to their 
+ 	documentation.
+	* gtk/gtksettings.c:
+	* gtk/gtktextview.c: Make the im-module property documentation more 
+	expansive.
+
 2009-01-15  Diego Escalante Urrelo  <diegoe@gnome.org>
 
 	Bug 562701 – GtkEntryCompletion popup sizes its rows wrong
diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c
index c8c14e6534..a5f84c4fa8 100644
--- a/gtk/gtkentry.c
+++ b/gtk/gtkentry.c
@@ -1089,10 +1089,12 @@ gtk_entry_class_init (GtkEntryClass *class)
   /**
    * GtkEntry:im-module:
    *
-   * Which IM module should be used for this entry.
+   * Which IM (input method) module should be used for this entry. 
+   * See #GtkIMContext.
    * 
    * Setting this to a non-%NULL value overrides the
-   * system-wide IM module setting. See #GtkSettings:gtk-im-module
+   * system-wide IM module setting. See the GtkSettings 
+   * #GtkSettings:gtk-im-module property.
    *
    * Since: 2.16
    */  
diff --git a/gtk/gtkimcontext.c b/gtk/gtkimcontext.c
index 3887d4a58e..16ef87157a 100644
--- a/gtk/gtkimcontext.c
+++ b/gtk/gtkimcontext.c
@@ -35,6 +35,18 @@
  * is used by GTK+ text input widgets like #GtkEntry to map from key events to
  * Unicode character strings.
  *
+ * The user may change the current input method via a context menu, unless the   
+ * #GtkSettings:gtk-show-input-method-menu GtkSettings property is set to FALSE. 
+ * The default input method can be set programmatically via the 
+ * #GtkSettings:gtk-im-module GtkSettings property. Alternatively, you may set 
+ * the GTK_IM_MODULE environment variable as documented in #gtk-running.
+ *
+ * The #GtkEntry #GtkEntry:im-module and #GtkTextView #GtkTextView:im-module 
+ * properties may also be used to set input methods for specific widget 
+ * instances. For instance, a certain entry widget might be expected to contain 
+ * certain characters which would be easier to input with a certain input 
+ * method.
+ *
  * An input method may consume multiple key events in sequence and finally
  * output the composed result. This is called preediting, and an input method
  * may provide feedback about this process by displaying the intermediate
diff --git a/gtk/gtksettings.c b/gtk/gtksettings.c
index 1ec5ade207..b89957ddec 100644
--- a/gtk/gtksettings.c
+++ b/gtk/gtksettings.c
@@ -834,7 +834,11 @@ gtk_settings_class_init (GtkSettingsClass *class)
   /**
    * GtkSettings:gtk-im-module:
    *
-   * Which IM module should be used by default.
+   * Which IM (input method) module should be used by default. This is the 
+   * input method that will be used if the user has not explicitly chosen 
+   * another input method from the IM context menu.  
+   *
+   * See #GtkIMContext and see the #GtkSettings:gtk-show-input-method-menu property.
    */
   result = settings_install_property_parser (class,
 					     g_param_spec_string ("gtk-im-module",
diff --git a/gtk/gtktextview.c b/gtk/gtktextview.c
index 959721f53c..11d04904ba 100644
--- a/gtk/gtktextview.c
+++ b/gtk/gtktextview.c
@@ -666,10 +666,12 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    /**
     * GtkTextView:im-module:
     *
-    * Which IM module should be used for this widget.
+    * Which IM (input method) module should be used for this entry. 
+    * See #GtkIMContext.
     *
     * Setting this to a non-%NULL value overrides the
-    * system-wide IM module setting. See #GtkSettings:gtk-im-module
+    * system-wide IM module setting. See the GtkSettings 
+    * #GtkSettings:gtk-im-module property.
     *
     * Since: 2.16
     */