diff --git a/src/lib/subsys/initialization.dox b/src/lib/subsys/initialization.dox
index ed2d5abf27..561cd17bab 100644
--- a/src/lib/subsys/initialization.dox
+++ b/src/lib/subsys/initialization.dox
@@ -9,7 +9,7 @@
 Tor has a single entry point: tor_run_main() in main.c.  All the ways of
 starting a Tor process (ntmain.c, tor_main.c, and tor_api.c) work by invoking tor_run_main().
 
-The tor_run_main() function normally exits (\ref init_exceptwhen "1") by
+The tor_run_main() function normally exits (@ref init_exceptwhen "1") by
 returning: not by calling abort() or exit().  Before it returns, it calls
 tor_cleanup() in shutdown.c.
 
@@ -17,7 +17,7 @@ Conceptually, there are several stages in running Tor.
 
 1. First, we initialize those modules that do not depend on the
    configuration.  This happens in the first half of tor_run_main(), and the
-   first half of tor_init().  (\ref init_pending_refactor "2")
+   first half of tor_init().  (@ref init_pending_refactor "2")
 
 2. Second, we parse the command line and our configuration, and configure
    systems that depend on our configuration or state.  This configuration
@@ -33,16 +33,16 @@ Conceptually, there are several stages in running Tor.
    running.
 
 
-> \anchor init_exceptwhen 1. tor_run_main() _can_ terminate with a call to
+> @anchor init_exceptwhen 1. tor_run_main() _can_ terminate with a call to
 > abort() or exit(), but only when crashing due to a bug, or when forking to
 > run as a daemon.
 
-> \anchor init_pending_refactor 2. The pieces of code that I'm describing as
+> @anchor init_pending_refactor 2. The pieces of code that I'm describing as
 > "the first part of tor_init()" and so on deserve to be functions with their
 > own name.  I'd like to refactor them, but before I do so, there is some
 > slight reorganization that needs to happen.  Notably, the
 > nt_service_parse_options() call ought logically to be later in our
-> initialization sequence.  See \ticket{32447} for our refactoring progress.
+> initialization sequence.  See @ticket{32447} for our refactoring progress.
 
 
 @section subsys Subsystems and initialization
@@ -55,10 +55,10 @@ In simplest terms, a **subsytem** is a logically separate part of Tor that
 can be initialized, shut down, managed, and configured somewhat independently
 of the rest of the program.
 
-To define a subsystem, we declare a `const` instance of subsys_fns_t,
-describing the subsystem and a set of functions that initialize it,
-deconstruct it, and so on.  See the documentation for subsys_fns_t for a full
-list of these functions.
+The subsys_fns_t type describes a subsystem and a set of functions that
+initialize it, desconstruct it, and so on. To define a subsystem, we declare
+a `const` instance of subsys_fns_t.  See the documentation for subsys_fns_t
+for a full list of these functions.
 
 After defining a subsytem, it must be inserted in subsystem_list.c.  At that
 point, table-driven mechanisms in subsysmgr.c will invoke its functions when
diff --git a/src/lib/subsys/subsys.h b/src/lib/subsys/subsys.h
index 258d060bb8..324f4f2947 100644
--- a/src/lib/subsys/subsys.h
+++ b/src/lib/subsys/subsys.h
@@ -23,10 +23,11 @@ struct config_format_t;
  * All callbacks are optional -- if a callback is set to NULL, the subsystem
  * manager will treat it as a no-op.
  *
- * You should use c99 named-field initializers with this structure: we
- * will be adding more fields, often in the middle of the structure.
+ * You should use c99 named-field initializers with this structure, for
+ * readability and safety. (There are a lot of functions here, all of them
+ * optional, and many of them with similar signatures.)
  *
- * See \ref initialization for more information about initialization and
+ * See @ref initialization for more information about initialization and
  * shutdown in Tor.
  *
  * To make a new subsystem, you declare a const instance of this type, and
@@ -71,7 +72,7 @@ typedef struct subsys_fns_t {
   /**
    * Connect a subsystem to the message dispatch system.
    *
-   * This function should use the macros in \refdir{lib/pubsub} to register a
+   * This function should use the macros in @refdir{lib/pubsub} to register a
    * set of messages that this subsystem may publish, and may subscribe to.
    *
    * See pubsub_macros.h for more information, and for examples.