diff --git a/CHANGES b/CHANGES
index 5638fdc4..f5990bc2 100644
--- a/CHANGES
+++ b/CHANGES
@@ -18,6 +18,7 @@ LMDB 0.9.15 Release Engineering
 		Misc. Android/Windows cleanup
 	Documentation
 		Fix MDB_APPEND doc
+		Fix MDB_MAXKEYSIZE doc (ITS#8156)
 		Clarify mdb_dbi_open doc
 
 LMDB 0.9.14 Release (2014/09/20)
diff --git a/mdb.c b/mdb.c
index 8de9705b..e19b36db 100644
--- a/mdb.c
+++ b/mdb.c
@@ -378,12 +378,17 @@ typedef MDB_ID	txnid_t;
 	/**	The version number for a database's lockfile format. */
 #define MDB_LOCK_VERSION	 ((MDB_DEVEL) ? 999 : 1)
 
-	/**	@brief The max size of a key we can write, or 0 for dynamic max.
+	/**	@brief The max size of a key we can write, or 0 for computed max.
 	 *
-	 *	Define this as 0 to compute the max from the page size.  511
-	 *	is default for backwards compat: liblmdb <= 0.9.10 can break
-	 *	when modifying a DB with keys/dupsort data bigger than its max.
-	 *	#MDB_DEVEL sets the default to 0.
+	 *	This macro should normally be left alone or set to 0.
+	 *	Note that a database with big keys or dupsort data cannot be
+	 *	reliably modified by a liblmdb which uses a smaller max.
+	 *	The default is 511 for backwards compat, or 0 when #MDB_DEVEL.
+	 *
+	 *	Other values are allowed, for backwards compat.  However:
+	 *	A value bigger than the computed max can break if you do not
+	 *	know what you are doing, and liblmdb <= 0.9.10 can break when
+	 *	modifying a DB with keys/dupsort data bigger than its max.
 	 *
 	 *	Data items in an #MDB_DUPSORT database are also limited to
 	 *	this size, since they're actually keys of a sub-DB.  Keys and