--- a/lisp/syntax.el	Sat Jan 23 04:45:49 2010 -0600
+++ b/lisp/syntax.el	Sun Jan 24 00:26:10 2010 -0600
@@ -2,7 +2,7 @@
 
 ;; Copyright (C) 1993, 1997 Free Software Foundation, Inc.
 ;; Copyright (C) 1995 Sun Microsystems.
-;; Copyright (C) 2005 Ben Wing.
+;; Copyright (C) 2005, 2010 Ben Wing.
 
 ;; This file is part of XEmacs.
 
@@ -36,7 +36,20 @@
 
 (defun make-syntax-table (&optional oldtable)
   "Return a new syntax table.
-It inherits all characters from the standard syntax table."
+
+It inherits all characters from the standard syntax table.
+
+A syntax table is a char table of type `syntax' (see `make-char-table').
+The valid values are integers (intended to be syntax codes as generated by
+`syntax-string-to-code'), and the default result given by `get-char-table'
+is the syntax code for `word'. (Note: In 21.4 and prior, it was the code
+for `inherit'.)
+
+To modify a syntax table, you should normally use `modify-syntax-entry'
+rather than directly modify the table with `put-char-table'.
+
+See `modify-syntax-entry' for a description of the character codes used
+to indicate the various syntax classes."
   (make-char-table 'syntax))
 
 (defun syntax-after (pos)