diff --git a/ChangeLog b/ChangeLog
index 46684d9e14..7c2ae9a355 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2005-11-21  Tim-Philipp Müller  <tim at centricular dot net>
+
+	* gst/gstmessage.c:
+	  Improve docs for DURATION message (usage of duration parameter)
+	  (#320113)
+
 2005-11-20  Wim Taymans  <wim@fluendo.com>
 
 	* check/Makefile.am:
diff --git a/gst/gstmessage.c b/gst/gstmessage.c
index 0c87af0115..79140f384d 100644
--- a/gst/gstmessage.c
+++ b/gst/gstmessage.c
@@ -637,7 +637,10 @@ gst_message_new_element (GstObject * src, GstStructure * structure)
  * Create a new duration message. This message is posted by elements that
  * know the duration of a stream in a specific format. This message
  * is received by bins and is used to calculate the total duration of a
- * pipeline.
+ * pipeline. Elements may post a duration message with a duration of
+ * GST_CLOCK_TIME_NONE to indicate that the duration has changed and the 
+ * cached duration should be discarded. The new duration can then be 
+ * retrieved via a query.
  *
  * Returns: The new duration message.
  *
@@ -932,7 +935,10 @@ gst_message_parse_segment_done (GstMessage * message, GstFormat * format,
  * @format: Result location for the format
  * @duration: Result location for the duration
  *
- * Extracts the duration and format from the duration message.
+ * Extracts the duration and format from the duration message. The duration
+ * might be GST_CLOCK_TIME_NONE, which indicates that the duration has
+ * changed. Applications should always use a query to retrieve the duration
+ * of a pipeline.
  *
  * MT safe.
  */