diff --git a/cave_data/cavealiases.txt b/cave_data/cavealiases.txt
index f9d3503c3..21cccaa07 100644
--- a/cave_data/cavealiases.txt
+++ b/cave_data/cavealiases.txt
@@ -1,16 +1,18 @@
 ; This is the list of cave aliases which is parsed when a database reset is done.
 ; This capability created 3rd July 2024. 
-ggg
 
 ; This is IMPORTANT as it enables old logbook and wallet cave ids to be redirected to current cave ids.
 ; such as "2017_cucc_28" => "1623-290" is Fishface.
 
+; Note that this just creates aliases for historic ids, it does not rename any cave or file.
+
 ; The format is ("<alias identifier>","<target identifier>")
 ; e.g.
 ("2017_cucc_28", "1623-290")
 ("2012-0w-01",   "2012-ow-01") # catch the typo: zero for 'O'
 
 ; target identifiers must be all in lower case
+; target identifiers must be of a real cave that already exists in the system
 
 ; lines with initial semi-colon ; and anything after hash # are comments
 ; extra commas are ignored
@@ -18,7 +20,8 @@ ggg
 ; later aliases can reference earlier ones
 ; all upper- and lower-case variants are done automatically
 
-; various funnies to cope with cave names as found in logbooks
+
+; various funnies to cope with cave names as found in logbooks:
         ("kh", "1623-161"),
         ("161-kh", "1623-161"),
         ("204-steinBH", "1623-204"),