diff --git a/ChangeLog b/ChangeLog
index a693df95db..2c58446c2b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2008-09-06  Sven Herzberg  <sven@imendio.com>
+
+	Bug 551063 – deprecated marking without a link to what new code should
+	use
+
+	* gdk/gdkevents.c: added inline documentation for gdk_input_add() and
+	gdk_input_add_full(); added replacement hints into the deprecation
+	message
+
 2008-09-05  Michael Natterer  <mitch@imendio.com>
 
 	* gtk/gtkfilechooserdefault.c (file_list_drag_data_received_cb):
diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 848de72ec6..7af44421ba 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,11 @@
+2008-09-06  Sven Herzberg  <sven@imendio.com>
+
+	Bug 551063 – deprecated marking without a link to what new code should
+	use
+
+	* gdk/tmpl/input.sgml: dropped tmpl documentation for gdk_input_add()
+	and gdk_input_add_full()
+
 2008-09-06  Stefan Kost  <ensonic@users.sf.net>
 
 	* gdk-pixbuf/gdk-pixbuf-csource.xml:
diff --git a/docs/reference/gdk/tmpl/input.sgml b/docs/reference/gdk/tmpl/input.sgml
index 87e3aa2f10..0226a2a466 100644
--- a/docs/reference/gdk/tmpl/input.sgml
+++ b/docs/reference/gdk/tmpl/input.sgml
@@ -35,19 +35,14 @@ callbacks.</para></listitem>
 
 
 <!-- ##### FUNCTION gdk_input_add_full ##### -->
-<para>
-Establish a callback when a condition becomes true on
-a file descriptor.
-</para>
 
-@source: a file descriptor.
-@condition: the condition.
-@function: the callback function.
-@data: callback data passed to @function.
-@destroy: callback function to call with @data when the input
-  handler is removed.
-@Returns: a tag that can later be used as an argument to
- gdk_input_remove().
+
+@source: 
+@condition: 
+@function: 
+@data: 
+@destroy: 
+@Returns: 
 
 
 <!-- ##### ENUM GdkInputCondition ##### -->
@@ -88,17 +83,6 @@ structure or object that @data points to.
 
 
 <!-- ##### FUNCTION gdk_input_add ##### -->
-<para>
-Establish a callback when a condition becomes true on
-a file descriptor.
-</para>
-
-@source: a file descriptor.
-@condition: the condition.
-@function: the callback function.
-@data: callback data passed to @function.
-@Returns: a tag that can later be used as an argument to
- gdk_input_remove().
 
 
 <!-- ##### FUNCTION gdk_input_remove ##### -->
diff --git a/gdk/gdkevents.c b/gdk/gdkevents.c
index fde9ab125a..24a29a1fd9 100644
--- a/gdk/gdkevents.c
+++ b/gdk/gdkevents.c
@@ -1015,6 +1015,23 @@ gdk_io_invoke (GIOChannel   *source,
   return TRUE;
 }
 
+/**
+ * gdk_input_add_full:
+ * @source: a file descriptor.
+ * @condition: the condition.
+ * @function: the callback function.
+ * @data: callback data passed to @function.
+ * @destroy: callback function to call with @data when the input
+ * handler is removed.
+ *
+ * Establish a callback when a condition becomes true on
+ * a file descriptor.
+ *
+ * Returns: a tag that can later be used as an argument to
+ * gdk_input_remove().
+ *
+ * Deprecated: Use g_io_add_watch_full() on a #GIOChannel
+ */
 gint
 gdk_input_add_full (gint	      source,
 		    GdkInputCondition condition,
@@ -1048,6 +1065,21 @@ gdk_input_add_full (gint	      source,
   return result;
 }
 
+/**
+ * gdk_input_add:
+ * @source: a file descriptor.
+ * @condition: the condition.
+ * @function: the callback function.
+ * @data: callback data passed to @function.
+ *
+ * Establish a callback when a condition becomes true on
+ * a file descriptor.
+ *
+ * Returns: a tag that can later be used as an argument to
+ * gdk_input_remove().
+ *
+ * Deprecated: Use g_io_add_watch() on a #GIOChannel
+ */
 gint
 gdk_input_add (gint		 source,
 	       GdkInputCondition condition,