diff --git a/classes.cpp b/classes.cpp
index 579e224e..fa71b78f 100644
--- a/classes.cpp
+++ b/classes.cpp
@@ -1,6 +1,12 @@
 // Hyperbolic Rogue -- items, monsters, walls, lands, descriptions, etc.
 // Copyright (C) 2011-2018 Zeno Rogue, see 'hyper.cpp' for details
 
+/** \file classes.cpp
+ *  \brief items, monsters, walls, lands, descriptions, etc.
+ *
+ *  See content.cpp for actual items, monsters, walls and lands.
+ */
+
 namespace hr {
 
 // --- help ---
@@ -509,6 +515,7 @@ static const flagtype qsSMALLBF         = qsSMALLB | qsFIELD;
 static const flagtype qsSMALLBE         = qsSMALLB | qELLIPTIC;
 static const flagtype qsBP              = qBINARY | qPENROSE;
 
+/** list of available geometries */
 vector<geometryinfo> ginf = {
   {"{7,3}", "none",     "{7,3} (standard HyperRogue map)",            "HR",       7, 3, 0,         gcHyperbolic,       0, {{7, 5}}, eVariation::bitruncated},
   {"{6,3}", "none",     "{6,3} (euclidean Hex grid)",                 "euclid",   6, 3, 0,         gcEuclid,           0, {{7, FORBIDDEN}}, eVariation::bitruncated},
@@ -574,6 +581,7 @@ vector<geometryinfo> ginf = {
 
 #define X3(x) x, x, x
 
+/** list of available models (i.e., projections) */
 const modelinfo mdinf[int(mdPolynomial)+1] = {
   {"disk/Gans", "general perspective", "general perspective", mf::azimuthal | mf::conformal},
   {"half-plane", "inversion", "half-plane", mf::conformal},
diff --git a/classes.h b/classes.h
index 9735e7db..df5dba9d 100644
--- a/classes.h
+++ b/classes.h
@@ -1,3 +1,10 @@
+// Hyperbolic Rogue -- items, monsters, walls, lands, descriptions, etc.
+// Copyright (C) 2011-2018 Zeno Rogue, see 'hyper.cpp' for details
+
+/** \file classes.h
+ *  \brief header file for content
+ */
+
 namespace hr {
 
 typedef unsigned color_t;
diff --git a/content.cpp b/content.cpp
index 660cb060..ffcfdb2e 100644
--- a/content.cpp
+++ b/content.cpp
@@ -1,9 +1,14 @@
-// Hyperbolic Rogue
-// X-macros for items, monsters, walls, and lands
-// add new content at 'add new content here' so that constants do not change
-// old things are sorted according to type, but this is not necessary for new content
+// Hyperbolic Rogue -- items, monsters, walls, and lands
 // Copyright (C) 2011-2018 Zeno Rogue, see 'hyper.cpp' for details
 
+/** \file content.cpp
+ *  \brief X-macros for items, monsters, walls, and lands
+ *
+ *  Add new content at 'add new content here' so that constants do not change.
+ *  Old things are sorted according to type, but this is not necessary for new content.
+ */
+
+
 #ifndef MONSTER
 #define MONSTER(a,b,c,d,e,f,g,h)
 #endif
diff --git a/game.cpp b/game.cpp
index 99c5d744..9cf3aa9e 100644
--- a/game.cpp
+++ b/game.cpp
@@ -165,27 +165,27 @@ EX cellwalker cwt;
 EX inline cell*& singlepos() { return cwt.at; }
 EX inline bool singleused() { return !(shmup::on || multi::players > 1); }
 
-/** the main random number generator for the game
- *  all the random calls related to the game mechanics (land generation, AI...) should use hrngen
- *  random calls not related to the game mechanics (graphical effects) should not use hrngen
- * this ensures that the game should unfold exactly the same if given the same seed and the same input 
+/** the main random number generator for the game.
+ *  
+ * All the random calls related to the game mechanics (land generation, AI...) should use hrngen.
+ *
+ * Random calls not related to the game mechanics (graphical effects) should not use hrngen.
+ *
+ * This ensures that the game should unfold exactly the same if given the same seed and the same input.
  */
-
 std::mt19937 hrngen;
 
-/** initialize hrngen @see hrngen */
+/** initialize \link hrngen \endlink */
 EX void shrand(int i) {
   hrngen.seed(i);
   }
 
-/** generate a large number with hrngen */
+/** generate a large number with \link hrngen \endlink */
 EX int hrandpos() { return hrngen() & HRANDMAX; }
 
-/** A random integer from [0..i), generated from hrngen.
+/** A random integer from [0..i), generated from \link hrngen \endlink.
  *  We are using our own implementations rather than ones from <random>,
  *  to make sure that they return the same values on different compilers.
-m * 
- * @see hrngen
  **/
 
 EX int hrand(int i) { 
@@ -202,16 +202,14 @@ template<class T, class... U> T pick(T x, U... u) { std::initializer_list<T> i =
 template<class T> void hrandom_shuffle(T* x, int n) { for(int k=1; k<n; k++) swap(x[k], x[hrand(k+1)]); }
 #endif
 
-/** Use hrngen to generate a floating point number between 0 and 1.
- * @see hrngen
+/** Use \link hrngen \endlink to generate a floating point number between 0 and 1.
  */
 
 EX ld hrandf() { 
   return (hrngen() - hrngen.min()) / (hrngen.max() + 1.0 - hrngen.min());
   }
 
-/** Returns an integer corresponding to the current state of hrngen.
- *  @see hrngen
+/** Returns an integer corresponding to the current state of \link hrngen \endlink.
  */
 EX int hrandstate() {
   std::mt19937 r2 = hrngen;
diff --git a/hyper.h b/hyper.h
index 62354eeb..af45237c 100644
--- a/hyper.h
+++ b/hyper.h
@@ -1,7 +1,7 @@
 // Hyperbolic Rogue -- main header file
 // Copyright (C) 2011-2019 Zeno Rogue, see 'hyper.cpp' for details
 
-/** \file Hyper.h
+/** \file hyper.h
  *  \brief The main header file of HyperRogue
  *
  *  Contains general utility macros, various value macros, using clauses for standard library functions,
diff --git a/locations.cpp b/locations.cpp
index f4d29442..4e8c694d 100644
--- a/locations.cpp
+++ b/locations.cpp
@@ -190,7 +190,7 @@ template<class T> T* tailored_alloc(int degree) {
   return result;
   }
 
-/** Counterpart to @see tailored_alloc. */
+/** Counterpart to tailored_alloc(). */
 template<class T> void tailored_delete(T* x) {
   x->~T();  
   delete[] ((char*) (x));
@@ -206,7 +206,7 @@ extern int hrand(int);
 /** reverse directions are currently not implemented for heptagons */
 inline vector<int> reverse_directions(struct heptagon *c, int i) { throw "unimplemented"; }
 
-/** the walker structure is used for walking on surfaces defined via @see connection_table. @connection_table */
+/** the walker structure is used for walking on surfaces defined via \ref connection_table. */
 template<class T> struct walker {
   /** where we are at */
   T *at;