diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 51d51a67e..fdcafa76c 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,8 @@
+2006-01-18  Matthias Clasen  <mclasen@redhat.com>
+
+	* glib/tmpl/scanner.sgml: Add a note explaining peculiarities
+	of peek_token wrt to scope changes.  (#307922)
+	
 2006-01-17  Matthias Clasen  <mclasen@redhat.com>
 
 	* glib/tmpl/memory.sgml: Add a note about casting the results
diff --git a/docs/reference/glib/tmpl/scanner.sgml b/docs/reference/glib/tmpl/scanner.sgml
index 518fec60c..16317be07 100644
--- a/docs/reference/glib/tmpl/scanner.sgml
+++ b/docs/reference/glib/tmpl/scanner.sgml
@@ -9,10 +9,11 @@ a general purpose lexical scanner.
 The #GScanner and its associated functions provide a general purpose
 lexical scanner.
 </para>
-<para>
+
+<!--
 FIXME: really needs an example and more detail, but I don't completely
 understand it myself. Look at gtkrc.c for some code using the scanner.
-</para>
+-->
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
@@ -259,6 +260,15 @@ The token data is placed in the
 <structfield>next_line</structfield>, and
 <structfield>next_position</structfield> fields of the #GScanner structure.
 </para>
+<para>
+Note that, while the token is not removed from the input stream (i.e.
+the next call to g_scanner_get_next_token() will return the same token),
+it will not be reevaluated. This can lead to surprising results when
+changing scope after peeking for the next token. Getting the next token
+after switching the scope will return whatever was peeked before, 
+regardless of any symbols that may have been added or removed in the
+new scope. 
+</para>
 
 @scanner: a #GScanner.
 @Returns: the type of the token.