diff --git a/drawing.cpp b/drawing.cpp
index ace6088f..e63d2802 100644
--- a/drawing.cpp
+++ b/drawing.cpp
@@ -35,51 +35,53 @@ static const int POLY_TRIANGLES = (1<<22);      // made of TRIANGLES, not TRIANG
 static const int POLY_INTENSE = (1<<23);        // extra intense colors
 static const int POLY_DEBUG = (1<<24);          // debug this shape
 
-/** HyperRogue map rendering functions do not draw its data immediately; instead, they call the 'queue' functions
+/** \brief A graphical element that can be drawn. Objects are not drawn immediately but rather queued.
+ *
+ *  HyperRogue map rendering functions do not draw its data immediately; instead, they call the 'queue' functions
  *  which store the data to draw in hr::ptds. This approach lets us draw the elements in the correct order. 
  */
 
 struct drawqueueitem {
-  /** The higher the priority, the earlier we should draw this object. */
+  /** \brief The higher the priority, the earlier we should draw this object. */
   PPR prio;
-  /** Color of this object. */
+  /** \brief Color of this object. */
   color_t color;
-  /** Some priorities need extra sorting inside the given class. This attribute is used to specify the inner sorting priority. */
+  /** \brief Some priorities need extra sorting inside the given class. This attribute is used to specify the inner sorting priority. */
   int subprio;
-  /** Draw the object. */
+  /** \brief Draw the object. */
   virtual void draw() = 0;
-  /** Draw the object as background. */
+  /** \brief Draw the object as background. */
   virtual void draw_back() {}
   virtual ~drawqueueitem() {}
-  /** When minimizing OpenGL calls, we need to group items of the same color, etc. together. This value is used as an extra sorting key. */
+  /** \brief When minimizing OpenGL calls, we need to group items of the same color, etc. together. This value is used as an extra sorting key. */
   virtual color_t outline_group() = 0;
   };
 
-/** Drawqueueitem used to draw polygons. The majority of drawqueueitems fall here. */
+/** \brief Drawqueueitem used to draw polygons. The majority of drawqueueitems fall here. */
 struct dqi_poly : drawqueueitem {
-  /** see hr::band_shift */
+  /** \brief see hr::band_shift */
   ld band_shift;
-  /** matrix used to transform the model */
+  /** \brief matrix used to transform the model */
   transmatrix V;
-  /** a vector of GL vertices where the model is stored */
+  /** \brief a vector of GL vertices where the model is stored */
   const vector<glvertex> *tab;
-  /** the where does the model start */
+  /** \brief the where does the model start */
   int offset;
-  /** how many vertices in the model */
+  /** \brief how many vertices in the model */
   int cnt;
-  /** the offset in the texture vertices */
+  /** \brief the offset in the texture vertices */
   int offset_texture;
-  /** outline color */
+  /** \brief outline color */
   color_t outline;
-  /** width of boundary lines */
+  /** \brief width of boundary lines */
   double linewidth;
-  /** various flags */
+  /** \brief various flags */
   int flags;
-  /** Texture data for textured polygons. Requires POLY_TRIANGLES flag */
+  /** \brief Texture data for textured polygons. Requires POLY_TRIANGLES flag */
   struct basic_textureinfo *tinf;
-  /** used to find the correct side to draw in spherical geometries */
+  /** \brief used to find the correct side to draw in spherical geometries */
   hyperpoint intester;
-  /** temporarily cached data */
+  /** \brief temporarily cached data */
   float cache;
   void draw();
   void gldraw();
@@ -87,24 +89,24 @@ struct dqi_poly : drawqueueitem {
   virtual color_t outline_group() { return outline; }
   };
 
-/** Drawqueueitem used to draw lines */
+/** \brief Drawqueueitem used to draw lines */
 struct dqi_line : drawqueueitem {
-  /** see hr::band_shift */
+  /** \brief see hr::band_shift */
   ld band_shift;
-  /** starting and ending point */
+  /** \brief starting and ending point */
   hyperpoint H1, H2;
-  /** how accurately to render the line */
+  /** \brief how accurately to render the line */
   int prf;
-  /** width of this line */
+  /** \brief width of this line */
   double width;
   void draw();
   void draw_back();
   virtual color_t outline_group() { return color; }
   };
 
-/** Drawqueueitem used to draw strings, using sccreen coodinates */      
+/** \brief Drawqueueitem used to draw strings, using sccreen coodinates */      
 struct dqi_string : drawqueueitem {
-  /** text */
+  /** \brief text */
   string str;
   /** onscreen position */
   int x, y;
@@ -122,19 +124,19 @@ struct dqi_string : drawqueueitem {
 
 /** Drawqueueitem used to draw circles, using screen coordinates */
 struct dqi_circle : drawqueueitem {
-  /* onscreen position */
+  /** \brief onscreen position */
   int x, y;
-  /* circle size */
+  /** \brief circle size */
   int size;
-  /* which color should it be filled with */
+  /** \brief which color should it be filled with */
   color_t fillcolor;
-  /* width of the circle */
+  /** \brief width of the circle */
   double linewidth;
   void draw();
   virtual color_t outline_group() { return 2; }
   };
 
-/** Perform an arbitrary action. May temporarily change the model, etc. */
+/** \brief Perform an arbitrary action. May temporarily change the model, etc. */
 struct dqi_action : drawqueueitem {
   reaction_t action;
   dqi_action(const reaction_t& a) : action(a) {}
@@ -143,7 +145,7 @@ struct dqi_action : drawqueueitem {
   };
 #endif
 
-/** Return a reference to i-th component of col. 
+/** \brief Return a reference to i-th component of col. 
  *  \arg i For colors with alpha, A=0, R=1, G=2, B=3. For colors without alpha, R=0, G=1, B=2.
  */
 EX unsigned char& part(color_t& col, int i) {
diff --git a/game.cpp b/game.cpp
index 2d1c5c9e..332ab6b2 100644
--- a/game.cpp
+++ b/game.cpp
@@ -8,7 +8,7 @@
 #include "hyper.h"
 namespace hr {
 
-/** the main random number generator for the game.
+/** \brief the main random number generator for the game.
  *  
  * All the random calls related to the game mechanics (land generation, AI...) should use hrngen.
  *
@@ -18,15 +18,16 @@ namespace hr {
  */
 EX std::mt19937 hrngen;
 
-/** initialize \link hrngen \endlink */
+/** \brief initialize \link hrngen \endlink */
 EX void shrand(int i) {
   hrngen.seed(i);
   }
 
-/** generate a large number with \link hrngen \endlink */
+/** \brief generate a large number with \link hrngen \endlink */
 EX int hrandpos() { return hrngen() & HRANDMAX; }
 
-/** A random integer from [0..i), generated from \link hrngen \endlink.
+/** \brief 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.
  **/
@@ -430,7 +431,7 @@ EX cell *wormhead(cell *c) {
   return c;
   }  
   
-/** currently works for worms only */
+/** \brief currently works for worms only */
 EX bool sameMonster(cell *c1, cell *c2) {
   if(!c1 || !c2) return false;
   if(c1 == c2) return true;
diff --git a/hyperpoint.cpp b/hyperpoint.cpp
index 0acb89bb..6431f99a 100644
--- a/hyperpoint.cpp
+++ b/hyperpoint.cpp
@@ -22,6 +22,7 @@ eVariation variation;
 
 #if HDR
 /** \brief A point in our continuous space
+ *
  *  Originally used for representing points in the hyperbolic plane.
  *  Currently used for all kinds of supported spaces, as well as
  *  for all vector spaces (up to 4 dimensions). We are using
@@ -100,6 +101,7 @@ struct hyperpoint : array<ld, MAXMDIM> {
   };
 
 /** \brief A matrix acting on hr::hyperpoint 
+ *
  *  Since we are using homogeneous coordinates for hr::hyperpoint,
  *  rotations and translations can be represented
  *  as matrix multiplications. Other applications of matrices in HyperRogue 
@@ -711,6 +713,7 @@ EX transmatrix rgpushxto0(const hyperpoint& H) {
   }
 
 /** \brief Fix the numerical inaccuracies in the isometry T
+ *
  *  The nature of hyperbolic geometry makes the computations numerically unstable.
  *  The numerical errors tend to accumulate, eventually destroying the projection.
  *  This function fixes this problem by replacing T with a 'correct' isometry.
diff --git a/inventory.cpp b/inventory.cpp
index a3c5c367..94de7f7a 100644
--- a/inventory.cpp
+++ b/inventory.cpp
@@ -9,26 +9,27 @@
 namespace hr { 
 
 /** \brief Implementation of the Orb Strategy Mode. 
+ *
  * The most important functions called outside is hr::inv::show(). 
  */
 EX namespace inv {
 
 #if CAP_INV
-  /** is the Orb Strategy Mode active? */
+  /** \brief is the Orb Strategy Mode active? */
   EX bool on;
-  /** the number of Orbs used up in each type */
+  /** \brief the number of Orbs used up in each type */
   EX array<int, ittypes> usedup;
-  /** the number of Orbs remaining in each type -- it is recalculated based on your treasure and hr::inv::usedup after every move */
+  /** \brief the number of Orbs remaining in each type -- it is recalculated based on your treasure and hr::inv::usedup after every move */
   EX array<int, ittypes> remaining;
-  /** extra orbs can be added to OSM using -IX commandline option */
+  /** \brief extra orbs can be added to OSM using -IX commandline option */
   EX array<int, ittypes> extra_orbs;
 
-  /** random seed used for hr::inv::invr */
+  /** \brief random seed used for hr::inv::invr */
   EX int rseed;
-  /** have we used any 'forbidden' orbs? */
+  /** \brief have we used any 'forbidden' orbs? */
   EX bool usedForbidden;
   
-  /** initialize the OSM data for a new game */
+  /** \brief initialize the OSM data for a new game */
   EX void init() {
     rseed = hrandpos();
     usedForbidden = false;
@@ -67,7 +68,7 @@ EX namespace inv {
     {itGreenGrass, itOrbThorns}
     };
 
-  /** how many orbs can we get from Orb-of-Mirroring orb */
+  /** \brief how many orbs can we get from Orb-of-Mirroring orb */
   int mirrorqty0(eItem orb) {
     if(shmup::on && isShmupLifeOrb(orb)) 
       return 3;
@@ -114,15 +115,15 @@ EX namespace inv {
     return int(mirrorqty0(orb) * sqrt(1.000001+items[itPower]/20.));
     }
   
-  /** PRNG used for calculating how many Orbs you get for your collected treasure */
+  /** \brief PRNG used for calculating how many Orbs you get for your collected treasure */
   std::mt19937 invr;
   
-  /** initialize hr::inv::invr */
+  /** \brief initialize hr::inv::invr */
   void sirand(int i) {
     invr.seed(i);
     }
   
-  /** get the next random value from hr::inv::invr */
+  /** \brief get the next random value from hr::inv::invr */
   int irand(int i) {    
     return invr() % i;
     }
@@ -279,7 +280,7 @@ EX namespace inv {
       extra += extraline(tr, itr >= at ? (its(at)+"!") : "10-50");
     }
   
-  /** Compute how many orbs you get for your current treasure. This is called after every move, and should give consistent results */
+  /** \brief Compute how many orbs you get for your current treasure. This is called after every move, and should give consistent results */
   EX void compute() {
     extra = "";
     orbinfoline = "";
@@ -482,7 +483,7 @@ EX namespace inv {
   
   EX bool activating;
 
-  /** show the OSM Orb screen */
+  /** \brief show the OSM Orb screen */
   EX void show() {
   
     multi::cpid = 0; /* just in case */
diff --git a/locations.cpp b/locations.cpp
index 7630f6bd..ab1960e9 100644
--- a/locations.cpp
+++ b/locations.cpp
@@ -21,23 +21,23 @@ extern int cellcount, heptacount;
 #define NODIR 126
 #define NOBARRIERS 127
 
-/** Cell information for the game. struct cell builds on this */
+/** \brief Cell information for the game. struct cell builds on this */
 struct gcell {
 
 #if CAP_BITFIELD
-  /** which land does this cell belong to */
+  /** \brief which land does this cell belong to */
   eLand land : 8;
-  /** wall type (waNone for no walls) */
+  /** \brief wall type (waNone for no walls) */
   eWall wall : 8;
-  /** monster on this cell -- note that player characters are handled separately */
+  /** \brief monster on this cell -- note that player characters are handled separately */
   eMonster monst : 8;
-  /** item on this cell */
+  /** \brief item on this cell */
   eItem item : 8;
 
-  /** if this is a barrier, what lands on are on the sides? */
+  /** \brief if this is a barrier, what lands on are on the sides? */
   eLand barleft : 8, barright : 8; 
 
-  /** is it currently sparkling with lightning? */
+  /** \brief is it currently sparkling with lightning? */
   unsigned ligon : 1;
 
   signed 
@@ -91,7 +91,7 @@ struct gcell {
   
   } LHU;
 
-  /** wall parameter, used e.g. for remaining power of Bonfires and Thumpers */
+  /** \brief wall parameter, used e.g. for remaining power of Bonfires and Thumpers */
   char wparam;
   
   #ifdef CELLID
@@ -129,35 +129,35 @@ int gmod(int i, int j);
 
 template<class T> struct connection_table {
 
-  /** Table of moves. This is the maximum size, but tailored_alloc allocates less. */
+  /** \brief Table of moves. This is the maximum size, but tailored_alloc allocates less. */
   T* move_table[FULL_EDGE + (FULL_EDGE + sizeof(char*) - 1) / sizeof(char*)];
   
   unsigned char *spintable() { return (unsigned char*) (&move_table[full()->degree()]); }
 
-  /** get the full T from the pointer to this connection table */
+  /** \brief get the full T from the pointer to this connection table */
   T* full() { T* x = (T*) this; return (T*)((char*)this - ((char*)(&(x->c)) - (char*)x)); }
-  /** for the edge d, set the `spin` and `mirror` attributes */
+  /** \brief for the edge d, set the `spin` and `mirror` attributes */
   void setspin(int d, int spin, bool mirror) { 
     unsigned char& c = spintable() [d];
     c = spin;
     if(mirror) c |= 128;
     }
-  /** we are spin(i)-th neighbor of move[i] */
+  /** \brief we are spin(i)-th neighbor of move[i] */
   int spin(int d) { return spintable() [d] & 127; }
-  /** on non-orientable surfaces, the d-th edge may be mirrored */
+  /** \brief on non-orientable surfaces, the d-th edge may be mirrored */
   bool mirror(int d) { return spintable() [d] & 128; }  
-  /** 'fix' the edge number d to get the actual index in [0, degree()) */
+  /** \brief 'fix' the edge number d to get the actual index in [0, degree()) */
   int fix(int d) { return gmod(d, full()->degree()); }
-  /** T in the direction i */
+  /** \brief T in the direction i */
   T*& move(int i) { return move_table[i]; }
-  /** T in the direction i, modulo degree() */
+  /** \brief T in the direction i, modulo degree() */
   T*& modmove(int i) { return move(fix(i)); }
   unsigned char modspin(int i) { return spin(fix(i)); }
-  /** initialize the table */
+  /** \brief initialize the table */
   void fullclear() { 
     for(int i=0; i<full()->degree(); i++) move_table[i] = NULL;
     }
-  /** connect this in direction d0 to c1 in direction d1, possibly mirrored */
+  /** \brief connect this in direction d0 to c1 in direction d1, possibly mirrored */
   void connect(int d0, T* c1, int d1, bool m) {
     move(d0) = c1;
     c1->move(d1) = full();
@@ -170,10 +170,10 @@ template<class T> struct connection_table {
     }
   };
 
-/** Allocate a class T with a connection_table, but 
- *  with only `degree` connections. Also set yet
- *  unknown connections to NULL.
-
+/** \brief Allocate a class T with a connection_table, but with only `degree` connections. 
+ *
+ *  Also set yet unknown connections to NULL.
+ *
  * Generating the hyperbolic world consumes lots of
  * RAM, so we really need to be careful on low memory devices. 
  */
@@ -193,7 +193,7 @@ template<class T> T* tailored_alloc(int degree) {
   return result;
   }
 
-/** Counterpart to tailored_alloc(). */
+/** \brief Counterpart to hr::tailored_alloc(). */
 template<class T> void tailored_delete(T* x) {
   x->~T();  
   delete[] ((char*) (x));
@@ -206,31 +206,31 @@ static const struct revstep_t { revstep_t() {}} revstep;
 
 extern int hrand(int);
 
-/** the walker structure is used for walking on surfaces defined via \ref connection_table. */
+/** \brief the walker structure is used for walking on surfaces defined via \ref connection_table. */
 template<class T> struct walker {
-  /** where we are at */
+  /** \brief where we are at */
   T *at;
-  /** in which direction (edge) we are facing */
+  /** \brief in which direction (edge) we are facing */
   int spin;
-  /** are we mirrored */
+  /** \brief are we mirrored */
   bool mirrored;
   walker<T> (T *at = NULL, int s = 0, bool m = false) : at(at), spin(s), mirrored(m) { if(at) s = at->c.fix(s); }
-  /** spin by i to the left (or right, when mirrored */
+  /** \brief spin by i to the left (or right, when mirrored */
   walker<T>& operator += (int i) {
     spin = at->c.fix(spin+(mirrored?-i:i));
     return (*this);
     }
-  /** spin by i to the right (or left, when mirrored */
+  /** \brief spin by i to the right (or left, when mirrored */
   walker<T>& operator -= (int i) {
     spin = at->c.fix(spin-(mirrored?-i:i));
     return (*this);
     }
-  /** add wmirror to mirror this walker */
+  /** \brief add wmirror to mirror this walker */
   walker<T>& operator += (wmirror_t) {
     mirrored = !mirrored;
     return (*this);
     }
-  /** add wstep to make a single step, after which we are facing the T we were originally on */
+  /** \brief add wstep to make a single step, after which we are facing the T we were originally on */
   walker<T>& operator += (wstep_t) {
     at->cmove(spin);
     int nspin = at->c.spin(spin);
@@ -239,14 +239,14 @@ template<class T> struct walker {
     spin = nspin;
     return (*this);
     }
-  /** add wrev to face the other direction, may be non-deterministic and use hrand */
+  /** \brief add wrev to face the other direction, may be non-deterministic and use hrand */
   walker<T>& operator += (rev_t) {
     auto rd = reverse_directions(at, spin);
     if(rd.size() == 1) spin = rd[0];
     else spin = rd[hrand(rd.size())];
     return (*this);
     }
-  /** adding revstep is equivalent to adding rev and step */
+  /** \brief adding revstep is equivalent to adding rev and step */
   walker<T>& operator += (revstep_t) {
     (*this) += rev; return (*this) += wstep; 
     }
@@ -265,13 +265,13 @@ template<class T> struct walker {
   walker<T>& operator -- (int) { return (*this) -= 1; }
   template<class U> walker operator + (U t) const { walker<T> w = *this; w += t; return w; }
   template<class U> walker operator - (U t) const { walker<T> w = *this; w += (-t); return w; }
-  /** what T are we facing, without creating it */
+  /** \brief what T are we facing, without creating it */
   T*& peek() { return at->move(spin); }
-  /** what T are we facing, with creating it */
+  /** \brief what T are we facing, with creating it */
   T* cpeek() { return at->cmove(spin); }
-  /** would we create a new T if we stepped forwards? */
+  /** \brief would we create a new T if we stepped forwards? */
   bool creates() { return !peek(); }
-  /** mirror this walker with respect to the d-th edge */
+  /** \brief mirror this walker with respect to the d-th edge */
   walker<T> mirrorat(int d) { return walker<T> (at, at->c.fix(d+d - spin), !mirrored); }
   };
 
@@ -288,11 +288,13 @@ struct cdata {
   int bits;
   };
 
-/** Limit on the 'distance' value in heptagon. This value is signed (negative distances are used
-    in horocycle implementation. Distance is currently a short, and we need a bit of breathing room.
-    It would not be a technical problem to use a larger type, but 32000 is close to what fits in
-    the memory of a normal computer. Farlands appear close to this limit.
-    */
+/** \brief Limit on the 'distance' value in heptagon. 
+ * 
+ *  This value is signed (negative distances are used
+ *  in horocycle implementation. Distance is currently a short, and we need a bit of breathing room.
+ *  It would not be a technical problem to use a larger type, but 32000 is close to what fits in
+ *  the memory of a normal computer. Farlands appear close to this limit.
+ **/
     
 constexpr int global_distance_limit = 32000;
 
@@ -300,44 +302,45 @@ constexpr int global_distance_limit = 32000;
     data (e.g., circular dragon). It should be larger than global_distance_limit */
 constexpr int iteration_limit = 10000000;
 
-/** in bitruncated/irregular/Goldberg geometries, heptagons form the 
+/** \brief underlying tiling
+ *  in bitruncated/irregular/Goldberg geometries, heptagons form the 
  *  underlying regular tiling (not necessarily heptagonal); in pure
  *  geometries, they correspond 1-1 to tiles; in 'masterless' geometries
  *  heptagons are unused
  */
 
 struct heptagon {
-  /** Automata are used to generate the standard maps. s is the state of this automaton */
+  /** \brief Automata are used to generate the standard maps. s is the state of this automaton */
   hstate s : 6;
-  /** distance modulo 4, in heptagons */
+  /** \brief distance modulo 4, in heptagons */
   unsigned int dm4: 2;
-  /** distance from the origin; based on the final geometry of cells, not heptagons themselves */
+  /** \brief distance from the origin; based on the final geometry of cells, not heptagons themselves */
   short distance;
-  /** Wmerald/wineyard generator. May have different meaning in other geometries. */
+  /** \brief Wmerald/wineyard generator. May have different meaning in other geometries. */
   short emeraldval;
-  /** Palace pattern generator. May have different meaning in other geometries. */
+  /** \brief Palace pattern generator. May have different meaning in other geometries. */
   short fiftyval;
-  /** Zebra pattern generator. May have different meaning in other geometries. */
+  /** \brief Zebra pattern generator. May have different meaning in other geometries. */
   short zebraval;
-  /** Field quotient pattern ID. May have different meaning in other geometries. */
+  /** \brief Field quotient pattern ID. May have different meaning in other geometries. */
   int fieldval : 24;
-  /** the number of adjacent heptagons */
+  /** \brief the number of adjacent heptagons */
   unsigned char type : 8;
-  /** data for fractal landscapes */
+  /** \brief data for fractal landscapes */
   short rval0, rval1;
   /** for the main map, it contains the fractal landscape data
    *
    *  For alternate structures, cdata contains the pointer to the original.
    */
   struct cdata *cdata;
-  /** which central cell does this heptagon correspond too
+  /** \brief which central cell does this heptagon correspond too
    *  
    *  For alternate geometries, c7 is NULL
    */
   cell *c7;
-  /** associated generator of alternate structure, for Camelot and horocycles */
+  /** \brief associated generator of alternate structure, for Camelot and horocycles */
   heptagon *alt;
-  /** connection table */
+  /** \brief connection table */
   connection_table<heptagon> c;
   // DO NOT add any fields after connection_table! (see tailored_alloc)
   heptagon*& move(int d) { return c.move(d); }
@@ -379,23 +382,23 @@ struct cell : gcell {
 typedef walker<heptagon> heptspin;
 typedef walker<cell> cellwalker;
 
-/** A structure useful when walking on the cell graph in arbitrary way, 
-  * or listing cells in general.
+/** \brief A structure useful when walking on the cell graph in arbitrary way, or listing cells in general.
+  *
   * Only one celllister may be active at a time, using the stack semantics.
   * Only the most recently created one works; the previous one will resume 
   * working when this one is destroyed.
   */
 struct manual_celllister {
-  /** list of cells in this list */
+  /** \brief list of cells in this list */
   vector<cell*> lst;
   vector<int> tmps;
 
-  /** is the given cell on the list? */
+  /** \brief is the given cell on the list? */
   bool listed(cell *c) {
     return c->listindex >= 0 && c->listindex < isize(lst) && lst[c->listindex] == c;
     }
   
-  /** add a cell to the list */
+  /** \brief add a cell to the list */
   bool add(cell *c) {
     if(listed(c)) return false;
     tmps.push_back(c->listindex);
@@ -409,7 +412,7 @@ struct manual_celllister {
     }  
   };
   
-/** automatically generate a list of nearby cells */
+/** \brief automatically generate a list of nearby cells */
 struct celllister : manual_celllister {
   vector<int> dists;
   
@@ -417,7 +420,7 @@ struct celllister : manual_celllister {
     if(add(c)) dists.push_back(d);
     }
   
-  /** automatically generate a list of nearby cells
+  /** \brief automatically generate a list of nearby cells
   @param orig where to start
   @param maxdist maximum distance to cover
   @param maxcount maximum number of cells to cover
@@ -439,11 +442,11 @@ struct celllister : manual_celllister {
       }
     }
   
-  /** for a given cell c on the list, return its distance from orig */
+  /** \brief for a given cell c on the list, return its distance from orig */
   int getdist(cell *c) { return dists[c->listindex]; }
   };
 
-/** translate heptspins to cellwalkers and vice versa */
+/** \brief translate heptspins to cellwalkers and vice versa */
 static const struct cth_t { cth_t() {}} cth;
 inline heptspin operator+ (cellwalker cw, cth_t) { return heptspin(cw.at->master, cw.spin * DUALMUL, cw.mirrored); }
 inline cellwalker operator+ (heptspin hs, cth_t) { return cellwalker(hs.at->c7, hs.spin / DUALMUL, hs.mirrored); }
@@ -451,10 +454,6 @@ inline cellwalker operator+ (heptspin hs, cth_t) { return cellwalker(hs.at->c7,
 #endif
 
 #if HDR
-/** a structure for representing movements 
- *  mostly for 'proper' moves where s->move(d) == t,
- *  but also sometimes for other moves
- */
 
 constexpr int STRONGWIND = 99;
 constexpr int FALL = 98;
@@ -464,6 +463,12 @@ constexpr int JUMP = 95;
 
 namespace whirlwind { cell *jumpDestination(cell*); }
 
+/** \brief a structure for representing movements 
+ *
+ *  mostly for 'proper' moves where s->move(d) == t,
+ *  but also sometimes for other moves
+ */
+
 struct movei {
   cell *s;
   cell *t;
diff --git a/quotient.cpp b/quotient.cpp
index f2b174ae..8002c654 100644
--- a/quotient.cpp
+++ b/quotient.cpp
@@ -8,7 +8,7 @@
 #include "hyper.h"
 namespace hr {
 
-// --- quotient geometry ---
+/** \brief quotient spaces */
 
 EX namespace quotientspace {
   
diff --git a/racing.cpp b/racing.cpp
index 26256b93..8d28992e 100644
--- a/racing.cpp
+++ b/racing.cpp
@@ -8,6 +8,7 @@
 #include "hyper.h"
 namespace hr {
 
+/** \brief Racing mode */
 EX namespace racing {
 
 #if CAP_RACING
diff --git a/raycaster.cpp b/raycaster.cpp
index a5050bc4..0e5a13a4 100644
--- a/raycaster.cpp
+++ b/raycaster.cpp
@@ -9,6 +9,7 @@
 
 namespace hr {
 
+/** raycaster */
 EX namespace ray {
 
 #if CAP_RAY
diff --git a/reg3.cpp b/reg3.cpp
index bba34df6..66b856af 100644
--- a/reg3.cpp
+++ b/reg3.cpp
@@ -20,7 +20,7 @@ namespace binary {
   hyperpoint deparabolic3(hyperpoint h);
   }
 
-/** regular three-dimensional tessellations */
+/** \brief regular three-dimensional tessellations */
 EX namespace reg3 {
 
   #if HDR
@@ -41,7 +41,7 @@ EX namespace reg3 {
   EX ld strafedist;
   EX bool dirs_adjacent[16][16];
 
-  /** for adjacent directions a,b, next_dir[a][b] is the next direction adjacent to a, in (counter?)clockwise order from b */
+  /** \brief for adjacent directions a,b, next_dir[a][b] is the next direction adjacent to a, in (counter?)clockwise order from b */
   EX int next_dir[16][16];
 
   template<class T> ld binsearch(ld dmin, ld dmax, const T& f) {
@@ -455,7 +455,7 @@ EX namespace reg3 {
       }
     };
 
-  /** homology cover of the Seifert-Weber space */
+  /** \brief homology cover of the Seifert-Weber space */
   namespace seifert_weber {
   
     using crystal::coord;
@@ -909,7 +909,7 @@ EX namespace reg3 {
       fclose(f);
       }
     
-    /** address = (fieldvalue, state) */
+    /** \brief address = (fieldvalue, state) */
     typedef pair<int, int> address;
     
     /** nles[x] lists the addresses from which we can reach address x 
diff --git a/tour.cpp b/tour.cpp
index cf0dd61a..a42436d5 100644
--- a/tour.cpp
+++ b/tour.cpp
@@ -9,22 +9,22 @@
 namespace hr { 
 #if CAP_TOUR
 
-/** Variables and function related to Guided Tour and other presentations. */
+/** \brief Variables and function related to Guided Tour and other presentations. */
 EX namespace tour {
 
-/** are we currently in a presentation */
+/** \brief are we currently in a presentation */
 EX bool on;
 
-/** should the presentation texts be shown */
+/** \brief should the presentation texts be shown */
 EX bool texts = true;
 
 EX string tourhelp;
 
-/** index of the current slide */
+/** \brief index of the current slide */
 EX int currentslide;
 
 #if HDR
-/** a parameter for the slides' action function */
+/** \brief a parameter for the slides' action function */
 enum presmode { 
   pmStartAll = 0,
   pmStart = 1, pmFrame = 2, pmStop = 3, pmKey = 4, pmRestart = 5,
@@ -32,38 +32,38 @@ enum presmode {
   pmGeometry = 11, pmGeometryReset = 13, pmGeometryStart = 15
   };
 
-/** slide definition */
+/** \brief slide definition */
 struct slide { 
-  /** title of this slide */
+  /** \brief title of this slide */
   const char *name; 
-  /** ID (currently unused */
+  /** \brief ID (currently unused */
   int unused_id; 
-  /** various flags */
+  /** \brief various flags */
   flagtype flags; 
-  /** the helptext */
+  /** \brief the helptext */
   const char *help; 
-  /** This function is called while this slide is displayed. Parameter hr::tour::presmode mode says what should be done */
+  /** \brief This function is called while this slide is displayed. Parameter hr::tour::presmode mode says what should be done */
   function<void(presmode mode)> action;
   };  
 
-/** in which geometries does this slide work */
+/** \brief in which geometries does this slide work */
 namespace LEGAL {
   enum flagtype { NONE, UNLIMITED, HYPERBOLIC, ANY, NONEUC };
   }
 
-/** when Enter pressed while showing the text, skip to the next slide immediately */
+/** \brief when Enter pressed while showing the text, skip to the next slide immediately */
 static const flagtype QUICKSKIP=8;
-/** The final slide. Shows where the presentation ends */
+/** \brief The final slide. Shows where the presentation ends */
 static const flagtype FINALSLIDE=16;
-/** Pressing Enter while in another geometry should change slides immediately */
+/** \brief Pressing Enter while in another geometry should change slides immediately */
 static const flagtype QUICKGEO=32;
-/** This slide should be displayed in sidescreen mode */
+/** \brief This slide should be displayed in sidescreen mode */
 static const flagtype SIDESCREEN = 64;
-/** When changing geometries, show the name of the slide, instead of the current land */
+/** \brief When changing geometries, show the name of the slide, instead of the current land */
 static const flagtype USE_SLIDE_NAME = 128;
 #endif
 
-/** an auxiliary function to enable a visualization in the Canvas land */
+/** \brief an auxiliary function to enable a visualization in the Canvas land */
 EX void setCanvas(presmode mode, char canv) {
   static char wc;
   static eLand ld;
@@ -83,7 +83,7 @@ EX void setCanvas(presmode mode, char canv) {
     }
   }
 
-/** static mode: we get Orbs of Teleport to use them instead of movement */
+/** \brief static mode: we get Orbs of Teleport to use them instead of movement */
 bool sickmode;
 
 EX function<eLand(eLand)> getNext;
@@ -94,13 +94,13 @@ EX function<bool(eLand)> showland;
 #define QUICKFIND quickfind = [](eLand l)
 #define SHOWLAND(f) showland = [](eLand l) { return f; }
 
-/** the caption of the special command (executed by pressing '5') in the current slide */
+/** \brief the caption of the special command (executed by pressing '5') in the current slide */
 EX string slidecommand;
 
-/** hooks to execute after calling presentation */
+/** \brief hooks to execute after calling presentation */
 EX hookset<void(int)> *hooks_slide;
 
-/** call action(mode) for the current slide. Also sets up some default stuff */
+/** \brief call action(mode) for the current slide. Also sets up some default stuff */
 EX void presentation(presmode mode) {
 
   cheater = 0;
@@ -118,7 +118,7 @@ EX void presentation(presmode mode) {
   callhooks(hooks_slide, mode);
   }
 
-/** display the help text for the current slide if texts enabled */
+/** \brief display the help text for the current slide if texts enabled */
 EX void slidehelp() {
   if(texts && slides[currentslide].help[0])
     gotoHelp(
@@ -128,7 +128,7 @@ EX void slidehelp() {
       );
   }
 
-/** return from a subgame launched while in presentation */
+/** \brief return from a subgame launched while in presentation */
 void return_geometry() {
   gamestack::pop();
   vid.scale = 1; vid.alpha = 1;
@@ -397,7 +397,7 @@ EX void start() {
     }
   }
 
-/** the default presentation (the Guided Tour) */
+/** \brief the default presentation (the Guided Tour) */
 EX slide default_slides[] = {
 #if ISMOBILE
   {"Note for mobiles", 10, LEGAL::NONE | QUICKSKIP,
@@ -850,7 +850,7 @@ EX slide default_slides[] = {
     }
   };
 
-/** currently used set of slides */
+/** \brief currently used set of slides */
 EX slide *slides = default_slides;
 
 auto a1 = addHook(hooks_frame, 100, [] () { if(tour::on) tour::presentation(tour::pmFrame); });