diff --git a/modules/standard/IO.chpl b/modules/standard/IO.chpl
index 20f531e20ca3..a51c991e7b4a 100644
--- a/modules/standard/IO.chpl
+++ b/modules/standard/IO.chpl
@@ -29,10 +29,6 @@ Input/output (I/O) facilities in Chapel include the types :record:`file`,
 :proc:`file.close`, :proc:`file.reader`, :proc:`file.writer`,
 :proc:`fileReader.read`, :proc:`fileWriter.write`, and many others.
 
-.. warning::
-  Please be aware, the IO Module documentation is under development and
-  currently contains some minor inconsistencies.
-
 
 Automatically Available Symbols
 -------------------------------
@@ -56,21 +52,23 @@ A :record:`file` in Chapel identifies a file in the underlying operating system.
 Reads to a file are done via one or more fileReaders associated with the file
 and writes to a file are done via one or more fileWriters.  Each
 :record:`fileReader` or :record:`fileWriter` uses a buffer to provide sequential
-read or write access to its file, optionally starting at an offset.
+read or write access to its file.
 
 For example, the following program opens a file and writes an integer to it:
 
 .. code-block:: chapel
 
+  use IO;
+
   try {
     // open the file "test-file.txt" for writing, creating it if
     // it does not exist yet.
     var myFile = open("test-file.txt", ioMode.cw);
 
-    // create a fileWriter starting at file offset 0
-    // (start and end offsets can be specified when creating the
-    // fileWriter)
-    var myFileWriter = myFile.writer();
+    // create a fileWriter starting at the beginning of the file
+    // (this fileWriter will not be used in parallel, so does not need to use
+    // locking)
+    var myFileWriter = myFile.writer(locking=false);
 
     var x: int = 17;
 
@@ -92,14 +90,16 @@ Then, the following program can be used to read the integer:
 
 .. code-block:: chapel
 
+  use IO;
+
   try {
     // open the file "test-file.txt" for reading only
     var myFile = open("test-file.txt", ioMode.r);
 
-    // create a fileReader starting at file offset 0
-    // (start and end offsets can be specified when creating the
-    // fileReader)
-    var myFileReader = myFile.reader();
+    // create a fileReader starting at the beginning of the file
+    // (this fileReader will not be used in parallel, so does not need to use
+    // locking)
+    var myFileReader = myFile.reader(locking=false);
 
     var x: int;
 
@@ -126,6 +126,8 @@ a pair of variables ``x`` and ``y``.
 
 .. code-block:: chapel
 
+  use IO;
+
   var x: int;
   var y: real;
   /* reading into variable expressions, returning
@@ -353,7 +355,7 @@ Functions for fileReader and fileWriter Creation
 :proc:`file.reader` creates a :record:`fileReader` for reading from a file.
 
 The helper functions :proc:`openReader` and :proc:`openWriter` can also be used
-to open a file and create a ``fileReader`` or ``fileWriter`` to it in a
+to open a file and create a ``fileReader``/``fileWriter`` to it in a
 single step.
 
 .. _about-io-filereader-filewriter-synchronization:
@@ -364,15 +366,15 @@ Synchronization of fileReader and fileWriter Data and Avoiding Data Races
 FileReaders and fileWriters (and files) contain locks in order to keep their
 operation safe for multiple tasks. When creating a fileReader or fileWriter, it
 is possible to disable the lock (for performance reasons) by passing
-``locking=false`` to e.g.  file.writer().  Some ``fileReader`` and ``fileWriter``
-methods - in particular those beginning with the underscore - should only be
-called on locked fileReaders or fileWriters.  With these methods, it is possible
-to get or set the fileReader or fileWriter style, or perform I/O "transactions"
-(see :proc:`fileWriter.mark`, e.g.). To use these methods, e.g., first lock the
+``locking=false`` to e.g.  file.writer(), or by using
+:proc:`openReader`/:proc:`openWriter`.  Some ``fileReader`` and ``fileWriter``
+methods should only be called on locked fileReaders or fileWriters.  With these
+methods, it is possible to perform I/O "transactions" (see
+:proc:`fileWriter.mark`, e.g.). To use these methods, e.g., first lock the
 fileWriter with :proc:`fileWriter.lock`, call the methods you need, then unlock
 the fileWriter with :proc:`fileWriter.unlock`. Note that in the future, we may
-move to alternative ways of calling these functions that guarantee that they
-are not called on a fileReader or fileWriter without the appropriate locking.
+move to alternative ways of calling these functions that guarantee that they are
+not called on a fileReader or fileWriter without the appropriate locking.
 
 Besides data races that can occur if locking is not used in fileWriters when it
 should be, it is also possible for there to be data races on file data that is
@@ -403,7 +405,7 @@ kind of data race can occur.
   Note that it is possible in some cases to create a :record:`file` that does
   not allow multiple fileWriters and/or fileReaders at different
   offsets. FileWriters created on such files will not change the file's offset
-  based on a ``start=`` offset arguments. Instead, each read or write operation
+  based on a ``region=`` offset argument. Instead, each read or write operation
   will use the file descriptor's current offset. Therefore, only one
   fileWriter or fileReader should be created for files created in the following
   situations:
@@ -419,8 +421,8 @@ Performing I/O with FileReaders and FileWriters
 FileReaders have a variety of read methods and fileWriters have a variety of
 write methods. The most common variety of these are generic methods that can
 read or write values of any type. For non-primitive types, the relevant
-``readThis`` or ``writeThis`` method is used to control the I/O formatting; see
-:ref:`serialize-deserialize`. These functions generally take any number of
+``deserialize`` or ``serialize`` method is used to control the I/O formatting;
+see :ref:`serialize-deserialize`. These functions generally take any number of
 arguments and `throw` if there was an error:
 
  * :proc:`fileWriter.write`
@@ -508,16 +510,15 @@ operating system streams standard input, standard output, and standard error.
 :var:`stdout` and :var:`stderr` support writing.
 
 All three are safe to use concurrently.
-Their types' ``kind`` argument is ``dynamic``.
 
 .. _about-io-error-handling:
 
 Error Handling
 --------------
 
-Most I/O routines throw a :class:`~OS.SystemError`, which can be handled
+Most I/O routines throw an :class:`~Errors.Error`, which can be handled
 appropriately with ``try`` and ``catch`` (see the
-:ref:`documentation<Complete_handling>` for more detail).
+:ref:`documentation<Handling_Errors>` for more detail).
 
 Additionally, some subclasses of :class:`~Errors.Error` are commonly used within
 the I/O implementation. These are:
@@ -540,6 +541,8 @@ recovered from separately from a ``SystemError``. See the following example:
 
 .. code-block:: chapel
 
+  use IO;
+
   const r = openReader("test.txt");
 
   try {
@@ -582,12 +585,17 @@ The steps of a typical *I/O transaction* are as follows:
 
 * ``mark`` the current file offset with :proc:`fileReader.mark` or
   :proc:`fileWriter.mark`. This pushes the current offset onto the *mark stack*
+
 * do a speculative I/O operation:
+
     * reading example: read 200 bytes followed by a `b`.
-    * writing example: write 200 bytes without exceeding the ``fileWriter``'s region.
+    * writing example: write 200 bytes without exceeding the ``fileWriter``'s
+      region.
+
 * if the operation fails, ``revert`` the operation by calling :proc:`fileReader.revert`
   or :proc:`fileWriter.revert`. Subsequent operations will continue from the
   originally marked offset as if nothing happened.
+
 * if the operation is successful, call :proc:`fileReader.commit` or
   :proc:`fileWriter.commit` to pop the value from the *mark stack* and continue
   performing I/O operations from the current offset.
@@ -622,7 +630,7 @@ See the following example of a simple I/O transaction:
 
 .. _filereader-filewriter-regions:
 
-Specifying the region of a FileReader or FileWriter
+Specifying the region of a fileReader or fileWriter
 ---------------------------------------------------
 
 The :record:`fileReader` and :record:`fileWriter` types can be configured to
@@ -699,9 +707,8 @@ useful in a procedure that relies on a ``reader`` argument being locking:
     // use 'reader' concurrently with another fileReader/fileWriter   ...
   }
 
-By default, a ``fileReader`` or ``fileWriter`` will lock. A non-locking reader
-or writer can be created by setting ``locking=false`` in one of the following
-routines:
+The ``locking`` field can be set by passing the desired value to one of the
+following routines that create a :record:`fileReader` or :record:`fileWriter`:
 
 * :proc:`file.reader`
 * :proc:`file.writer`
@@ -709,8 +716,8 @@ routines:
 * :proc:`openWriter`
 
 With a locking ``fileReader`` or ``fileWriter``, one can obtain a lock manually
-by calling :proc:`fileReader.lock` or :proc:`fileWriter.lock`, and then release a
-lock by calling :proc:`fileReader.unlock` or :proc:`fileWriter.unlock`.
+by calling :proc:`fileReader.lock` or :proc:`fileWriter.lock`, and then release
+a lock by calling :proc:`fileReader.unlock` or :proc:`fileWriter.unlock`.
 
 .. note::
   The following methods will not automatically acquire/release a lock for
@@ -883,7 +890,7 @@ enum endianness {
   little = 2
 }
 
-@deprecated(":enum: ioendian is deprecated; please use :enum: endianness instead")
+@deprecated(":enum:`ioendian` is deprecated; please use :enum:`endianness` instead")
 type ioendian = endianness;
 
 
@@ -1755,7 +1762,7 @@ a C ``FILE`` object can be obtained via Chapel's
   This is an alternative way to create a :record:`file`.  The main way to do so
   is via the :proc:`open` function.
 
-Once the Chapel file is created, you will need to use a :proc:`file.reader` to
+Once the Chapel file is created, you will need to use :proc:`file.reader` to
 create a fileReader or :proc:`file.writer` to create a fileWriter to perform I/O
 operations on the C file.
 
@@ -2495,7 +2502,7 @@ record defaultSerializer {
 
     Classes and records will have their ``serialize`` method invoked, passing
     in ``writer`` and this Serializer as arguments. Please see the
-    :ref:`serializers technote<ioSerializers>` for more.
+    :ref:`serializers technote<ioSerializers>` for more information.
 
     Classes and records are expected to implement the ``writeSerializable``
     or ``serializable`` interface.
@@ -2542,7 +2549,7 @@ record defaultSerializer {
     :arg name: The name of the record type.
     :arg size: The number of fields in the record.
 
-    :returns: A new AggregateSerializer
+    :returns: A new :type:`AggregateSerializer`
   */
   proc startRecord(writer: fileWriter, name: string, size: int) throws {
     writer.writeLiteral("(");
@@ -2620,7 +2627,7 @@ record defaultSerializer {
       :arg name: The name of the class type.
       :arg size: The number of fields in the class.
 
-      :returns: A new AggregateSerializer
+      :returns: A new :record:`~IO.defaultSerializer.AggregateSerializer`
     */
     proc ref startClass(writer: fileWriter, name: string, size: int) throws {
       // Note: 'size' of parent might be zero, but 'size' of grandparent might
@@ -2659,7 +2666,7 @@ record defaultSerializer {
     :arg writer: The ``fileWriter`` to be used when serializing.
     :arg size: The number of elements in the tuple.
 
-    :returns: A new TupleSerializer
+    :returns: A new :record:`TupleSerializer`
   */
   proc startTuple(writer: fileWriter, size: int) throws {
     writer.writeLiteral("(");
@@ -2722,7 +2729,7 @@ record defaultSerializer {
     :arg writer: The ``fileWriter`` to be used when serializing.
     :arg size: The number of elements in the list.
 
-    :returns: A new ListSerializer
+    :returns: A new :record:`ListSerializer`
   */
   proc startList(writer: fileWriter, size: int) throws {
     writer.writeLiteral("[");
@@ -2775,14 +2782,15 @@ record defaultSerializer {
     :arg writer: The ``fileWriter`` to be used when serializing.
     :arg size: The number of elements in the array.
 
-    :returns: A new ArraySerializer
+    :returns: A new :record:`ArraySerializer`
   */
   proc startArray(writer: fileWriter, size: int) throws {
     return new ArraySerializer(writer);
   }
 
   /*
-    Returned by ``startArray`` to provide the API for serializing arrays.
+    Returned by :proc:`~IO.defaultSerializer.startArray` to provide the API for
+    serializing arrays.
 
     In the default format, an array will be serialized as a
     whitespace-separated series of serialized elements.
@@ -2819,7 +2827,7 @@ record defaultSerializer {
       22 23 24
       25 26 27
 
-    Empty arrays result in no output to the ``fileWriter``.
+    Empty arrays result in no output to the :record:`fileWriter`.
   */
   record ArraySerializer {
     @chpldoc.nodoc
@@ -2832,8 +2840,8 @@ record defaultSerializer {
     var _first : bool = true;
 
     /*
-      Inform the ``ArraySerializer`` to start serializing a new dimension of
-      size ``size``.
+      Inform the :record:`~IO.defaultSerializer.ArraySerializer` to start
+      serializing a new dimension of size ``size``.
     */
     proc ref startDim(size: int) throws {
       _arrayDim += 1;
@@ -2876,7 +2884,7 @@ record defaultSerializer {
     :arg writer: The ``fileWriter`` to be used when serializing.
     :arg size: The number of entries in the map.
 
-    :returns: A new MapSerializer
+    :returns: A new :record:`MapSerializer`
   */
   proc startMap(writer: fileWriter, size: int) throws {
     writer.writeLiteral("{");
@@ -2884,7 +2892,8 @@ record defaultSerializer {
   }
 
   /*
-    Returned by ``startMap`` to provide the API for serializing maps.
+    Returned by :proc:`~IO.defaultSerializer.startMap` to provide the API for
+    serializing maps.
 
     Maps are serialized as a comma-separated series of pairs between curly
     braces. Pairs are serialized with a ``:`` separating the key and value. For
@@ -2933,7 +2942,7 @@ record defaultSerializer {
 }
 
 /*
-  The default Deserializer used by ``fileReader``.
+  The default Deserializer used by :record:`fileReader`.
 
   See :ref:`the serializers technote<ioSerializers>` for a general overview
   of Deserializers and their usage.
@@ -2964,14 +2973,15 @@ record defaultDeserializer {
     Classes and records will be deserialized using an appropriate initializer,
     passing in ``reader`` and this Deserializer as arguments. If an
     initializer is unavailable, this method may invoke the class or record's
-    ``deserialize`` method. Please see the :ref:`serializers technote<ioSerializers>` for more.
+    ``deserialize`` method. Please see the
+    :ref:`serializers technote<ioSerializers>` for more information.
 
     Classes and records are expected to implement either the
     ``initDeserializable`` or ``readDeserializable`` interfaces (or both).
     Alternatively, types implementing the entire ``serializable`` interface
     are also accepted.
 
-    :arg reader: The ``fileReader`` from which types are deserialized.
+    :arg reader: The :record:`fileReader` from which types are deserialized.
     :arg readType: The type to be deserialized.
 
     :returns: A value of type ``readType``.
@@ -3006,7 +3016,7 @@ record defaultDeserializer {
     than creating a new value. For classes and records, this method will first
     attempt to invoke a ``deserialize`` method. If the ``deserialize`` method
     is unavailable, this method may fall back on invoking a suitable
-    initializer and assigning the resulting value into ``val``.. Please see the
+    initializer and assigning the resulting value into ``val``. Please see the
     :ref:`serializers technote<ioSerializers>` for more.
 
     Classes and records are expected to implement either the
@@ -3014,7 +3024,7 @@ record defaultDeserializer {
     Alternatively, types implementing the entire ``serializable`` interface
     are also accepted.
 
-    :arg reader: The ``fileReader`` from which values are deserialized.
+    :arg reader: The :record:`fileReader` from which values are deserialized.
     :arg val: The value into which this Deserializer will deserialize.
   */
   proc ref deserializeValue(reader: fileReader, ref val: ?readType) : void throws {
@@ -3038,7 +3048,7 @@ record defaultDeserializer {
   /*
     Start deserializing a class by reading the character ``{``.
 
-    :arg reader: The ``fileReader`` to use when deserializing.
+    :arg reader: The :record:`fileReader` to use when deserializing.
     :arg name: The name of the class type
 
     :returns: A new :type:`AggregateDeserializer`
@@ -3051,7 +3061,7 @@ record defaultDeserializer {
   /*
     Start deserializing a record by reading the character ``(``.
 
-    :arg reader: The ``fileReader`` to use when deserializing.
+    :arg reader: The :record:`fileReader` to use when deserializing.
     :arg name: The name of the record type
 
     :returns: A new :type:`AggregateDeserializer`
@@ -3062,7 +3072,8 @@ record defaultDeserializer {
   }
 
   /*
-    Returned by ``startClass`` or ``startRecord`` to provide the API for
+    Returned by :proc:`~IO.defaultDeserializer.startClass` or
+    :proc:`~IO.defaultDeserializer.startRecord` to provide the API for
     deserializing classes or records.
 
     See :type:`~IO.defaultSerializer.AggregateSerializer` for details of the
@@ -3102,7 +3113,7 @@ record defaultDeserializer {
     /*
       Start deserializing a nested class inside the current class.
 
-      See ``defaultSerializer.AggregateSerializer.startClass`` for details
+      See :proc:`defaultSerializer.AggregateSerializer.startClass` for details
       on inheritance on the default format.
 
       :returns: A new AggregateDeserializer
@@ -3142,8 +3153,8 @@ record defaultDeserializer {
   /*
     Returned by ``startTuple`` to provide the API for deserializing tuples.
 
-    See ``defaultSerializer.TupleSerializer`` for details of the default format
-    for tuples.
+    See :record:`~IO.defaultSerializer.TupleSerializer` for details of the
+    default format for tuples.
   */
   record TupleDeserializer {
     @chpldoc.nodoc
@@ -3191,8 +3202,8 @@ record defaultDeserializer {
   /*
     Returned by ``startList`` to provide the API for deserializing lists.
 
-    See ``defaultSerializer.ListSerializer`` for details of the default format
-    for lists.
+    See :record:`~IO.defaultSerializer.ListSerializer` for details of the
+    default format for lists.
   */
   record ListDeserializer {
     @chpldoc.nodoc
@@ -3253,8 +3264,8 @@ record defaultDeserializer {
   /*
     Returned by ``startArray`` to provide the API for deserializing arrays.
 
-    See ``defaultSerializer.ArraySerializer`` for details of the default format
-    for arrays.
+    See :record:`~IO.defaultSerializer.ArraySerializer` for details of the
+    default format for arrays.
   */
   record ArrayDeserializer {
     @chpldoc.nodoc
@@ -3267,7 +3278,8 @@ record defaultDeserializer {
     var _arrayMax : int;
 
     /*
-      Inform the ``ArrayDeserializer`` to start deserializing a new dimension.
+      Inform the :record:`~IO.defaultDeserializer.ArrayDeserializer` to start
+      deserializing a new dimension.
     */
     proc ref startDim() throws {
       _arrayDim += 1;
@@ -3334,7 +3346,7 @@ record defaultDeserializer {
   /*
     Returned by ``startMap`` to provide the API for deserializing maps.
 
-    See ``defaultSerializer.MapSerializer`` for details of the default
+    See :record:`~IO.defaultSerializer.MapSerializer` for details of the default
     format for map.
   */
   record MapDeserializer {
@@ -3408,8 +3420,8 @@ record defaultDeserializer {
 @unstable("This config param is unstable and may be removed without advance notice")
 /*
   This config param allows users to disable a warning for reading and writing
-  classes and strings with ``binarySerializer`` and ``binaryDeserializer``
-  following a format change in the 1.33 release.
+  classes and strings with :record:`~IO.binarySerializer` and
+  :record:`binaryDeserializer` following a format change in the 1.33 release.
 */
 config param warnBinaryStructured : bool = true;
 
@@ -3492,8 +3504,8 @@ record binarySerializer {
     Serialize ``val`` with ``writer``.
 
     Numeric values like integers, real numbers, and complex numbers are
-    serialized directly to the associated ``fileWriter`` as binary data in the
-    specified endianness.
+    serialized directly to the associated :record:`fileWriter` as binary data in
+    the specified endianness.
 
     Booleans are serialized as single byte unsigned values of either ``0`` or
     ``1``.
@@ -3578,8 +3590,9 @@ record binarySerializer {
   }
 
   /*
-    Returned by ``startClass`` or ``startRecord`` to provide the API for
-    serializing classes or records.
+    Returned by :proc:`~IO.binarySerializer.startClass` or
+    :proc:`~IO.binarySerializer.startRecord` to provide the API for serializing
+    classes or records.
 
     In this simple binary format, classes and records do not begin or end with
     any bytes indicating size, and instead serialize their field values in
@@ -3593,7 +3606,7 @@ record binarySerializer {
     var writer : fileWriter(false, binarySerializer);
 
     /*
-      Serialize ``field`` in ``binarySerializer``'s format.
+      Serialize ``field`` in :record:`binarySerializer`'s format.
     */
     proc writeField(name: string, const field: ?T) throws {
       writer.write(field);
@@ -3621,9 +3634,9 @@ record binarySerializer {
   }
 
   /*
-    Start serializing a tuple and return a new ``TupleSerializer``.
+    Start serializing a tuple and return a new :record:`TupleSerializer`.
 
-    :arg writer: The ``fileWriter`` to be used when serializing.
+    :arg writer: The :record:`fileWriter` to be used when serializing.
     :arg size: The number of elements in the tuple.
 
     :returns: A new TupleSerializer
@@ -3633,18 +3646,19 @@ record binarySerializer {
   }
 
   /*
-    Returned by ``startTuple`` to provide the API for serializing tuples.
+    Returned by :proc:`~IO.binarySerializer.startTuple` to provide the API for
+    serializing tuples.
 
     In this simple binary format, tuples do not begin or end with any bytes
     indicating size, and instead serialize their elements sequentially in
-    ``binarySerializer``'s format.
+    :record:`binarySerializer`'s format.
   */
   record TupleSerializer {
     @chpldoc.nodoc
     var writer : fileWriter(false, binarySerializer);
 
     /*
-      Serialize ``element`` in ``binarySerializer``'s format.
+      Serialize ``element`` in :record:`binarySerializer`'s format.
     */
     proc writeElement(const element: ?T) throws {
       writer.write(element);
@@ -3660,10 +3674,10 @@ record binarySerializer {
   /*
     Start serializing a list by serializing ``size``.
 
-    :arg writer: The ``fileWriter`` to be used when serializing.
+    :arg writer: The :record:`fileWriter` to be used when serializing.
     :arg size: The number of elements in the list.
 
-    :returns: A new ListSerializer
+    :returns: A new :record:`ListSerializer`
   */
   proc startList(writer: fileWriter(?), size: int) throws {
     writer.write(size);
@@ -3671,7 +3685,8 @@ record binarySerializer {
   }
 
   /*
-    Returned by ``startList`` to provide the API for serializing lists.
+    Returned by :proc:`~IO.binarySerializer.startList` to provide the API for
+    serializing lists.
 
     In this simple binary format, lists begin with the serialization of an
     ``int`` representing the size of the list. This data is then followed by
@@ -3682,7 +3697,7 @@ record binarySerializer {
     var writer : fileWriter(false, binarySerializer);
 
     /*
-      Serialize ``element`` in ``binarySerializer``'s format.
+      Serialize ``element`` in :record:`binarySerializer`'s format.
     */
     proc writeElement(const element: ?) throws {
       writer.write(element);
@@ -3696,9 +3711,9 @@ record binarySerializer {
   }
 
   /*
-    Start serializing an array and return a new ``ArraySerializer``.
+    Start serializing an array and return a new :record:`ArraySerializer`.
 
-    :arg writer: The ``fileWriter`` to be used when serializing.
+    :arg writer: The :record:`fileWriter` to be used when serializing.
     :arg size: The number of elements in the array.
 
     :returns: A new ArraySerializer
@@ -3708,10 +3723,11 @@ record binarySerializer {
   }
 
   /*
-    Returned by ``startArray`` to provide the API for serializing arrays.
+    Returned by :proc:`~IO.binarySerializer.startArray` to provide the API for
+    serializing arrays.
 
     In this simple binary format, arrays are serialized element by element
-    in the order indicated by the caller of ``writeElement``. Dimensions and
+    in the order indicated by the caller of :proc:`writeElement`. Dimensions and
     the start or end of the array are not represented.
   */
   record ArraySerializer {
@@ -3733,7 +3749,7 @@ record binarySerializer {
     }
 
     /*
-      Serialize ``element`` in ``binarySerializer``'s format.
+      Serialize ``element`` in :record:`binarySerializer`'s format.
     */
     proc writeElement(const element: ?) throws {
       writer.write(element);
@@ -3750,7 +3766,8 @@ record binarySerializer {
       .. note::
 
         This method is only optimized for the case where the
-        ``binarySerializer`` has been configured for ``native`` endianness.
+        :record:`binarySerializer` has been configured for ``native``
+        endianness.
 
       .. warning::
 
@@ -3778,10 +3795,10 @@ record binarySerializer {
   /*
     Start serializing a map by serializing ``size``.
 
-    :arg writer: The ``fileWriter`` to be used when serializing.
+    :arg writer: The :record:`fileWriter` to be used when serializing.
     :arg size: The number of entries in the map.
 
-    :returns: A new MapSerializer
+    :returns: A new :record:`MapSerializer`
   */
   proc startMap(writer: fileWriter(?), size: int) throws {
     writer.write(size);
@@ -3789,7 +3806,8 @@ record binarySerializer {
   }
 
   /*
-    Returned by ``startMap`` to provide the API for serializing maps.
+    Returned by :proc:`~IO.binarySerializer.startMap` to provide the API for
+    serializing maps.
 
     In this simple binary format, maps begin with the serialization of an
     ``int`` representing the size of the map. This data is then followed by the
@@ -3802,14 +3820,14 @@ record binarySerializer {
     var writer : fileWriter(false, binarySerializer);
 
     /*
-      Serialize ``key`` in ``binarySerializer``'s format.
+      Serialize ``key`` in :record:`binarySerializer`'s format.
     */
     proc writeKey(const key: ?) throws {
       writer.write(key);
     }
 
     /*
-      Serialize ``val`` in ``binarySerializer``'s format.
+      Serialize ``val`` in :record:`binarySerializer`'s format.
     */
     proc writeValue(const val: ?) throws {
       writer.write(val);
@@ -3839,9 +3857,9 @@ record binarySerializer {
 
   .. note::
 
-    Deserializing ``string`` or ``bytes`` types will result in an
-    IllegalArgumentError because these types cannot currently be deserialized
-    with the raw nature of the format.
+    Deserializing :type:`~String.string` or :type:`~Bytes.bytes` types will
+    result in an :type:`~Errors.IllegalArgumentError` because these types cannot
+    currently be deserialized with the raw nature of the format.
 
   .. warning::
 
@@ -3921,7 +3939,7 @@ record binaryDeserializer {
     ``initDeserializable`` or ``readDeserializable`` interfaces (or both). The
     ``serializable`` interface is also acceptable.
 
-    :arg reader: The ``fileReader`` from which types are deserialized.
+    :arg reader: The :record:`fileReader` from which types are deserialized.
     :arg readType: The type to be deserialized.
 
     :returns: A value of type ``readType``.
@@ -3969,14 +3987,14 @@ record binaryDeserializer {
     than creating a new value. For classes and records, this method will first
     attempt to invoke a ``deserialize`` method. If the ``deserialize`` method
     is unavailable, this method may fall back on invoking a suitable
-    initializer and assigning the resulting value into ``val``.. Please see the
+    initializer and assigning the resulting value into ``val``. Please see the
     :ref:`serializers technote<ioSerializers>` for more.
 
     Classes and records are expected to implement either the
     ``readDeserializable`` or ``initDeserializable`` interfaces (or both). The
     ``serializable`` interface is also acceptable.
 
-    :arg reader: The ``fileReader`` from which values are deserialized.
+    :arg reader: The :record:`fileReader` from which values are deserialized.
     :arg val: The value into which this Deserializer will deserialize.
   */
   proc ref deserializeValue(reader: fileReader(?), ref val: ?readType) : void throws {
@@ -3994,9 +4012,9 @@ record binaryDeserializer {
   }
 
   /*
-    Start deserializing a class by returning an ``AggregateDeserializer``.
+    Start deserializing a class by returning an :record:`AggregateDeserializer`.
 
-    :arg reader: The ``fileReader`` to use when deserializing.
+    :arg reader: The :record:`fileReader` to use when deserializing.
     :arg name: The name of the class type.
 
     :returns: A new :type:`AggregateDeserializer`
@@ -4006,9 +4024,10 @@ record binaryDeserializer {
   }
 
   /*
-    Start deserializing a record by returning an ``AggregateDeserializer``.
+    Start deserializing a record by returning an
+    :record:`AggregateDeserializer`.
 
-    :arg reader: The ``fileReader`` to use when deserializing.
+    :arg reader: The :record:`fileReader` to use when deserializing.
     :arg name: The name of the record type.
 
     :returns: A new :type:`AggregateDeserializer`
@@ -4018,10 +4037,11 @@ record binaryDeserializer {
   }
 
   /*
-    Returned by ``startClass`` or ``startRecord`` to provide the API for
+    Returned by :proc:`~IO.binaryDeserializer.startClass` or
+    :proc:`~IO.binaryDeserializer.startRecord` to provide the API for
     deserializing classes or records.
 
-    See ``binarySerializer.AggregateSerializer`` for details of the
+    See :record:`binarySerializer.AggregateSerializer` for details of the
     binary format for classes and records.
   */
   record AggregateDeserializer {
@@ -4045,10 +4065,10 @@ record binaryDeserializer {
     /*
       Start deserializing a nested class inside the current class.
 
-      See ``binarySerializer.AggregateSerializer.startClass`` for details
+      See :proc:`binarySerializer.AggregateSerializer.startClass` for details
       on inheritance on the binary format.
 
-      :returns: A new AggregateDeserializer
+      :returns: A new :record:`~IO.binaryDeserializer.AggregateDeserializer`
     */
     proc startClass(reader, name: string) throws {
       return this;
@@ -4068,9 +4088,9 @@ record binaryDeserializer {
   }
 
   /*
-    Start deserializing a tuple by returning a ``TupleDeserializer``.
+    Start deserializing a tuple by returning a :record:`TupleDeserializer`.
 
-    :arg reader: The ``fileReader`` to use when deserializing.
+    :arg reader: The :record:`fileReader` to use when deserializing.
 
     :returns: A new :type:`TupleDeserializer`
   */
@@ -4079,10 +4099,11 @@ record binaryDeserializer {
   }
 
   /*
-    Returned by ``startTuple`` to provide the API for deserializing tuples.
+    Returned by :proc:`~IO.binaryDeserializer.startTuple` to provide the API for
+    deserializing tuples.
 
-    See ``binarySerializer.TupleSerializer`` for details of the binary format
-    for tuples.
+    See :record:`binarySerializer.TupleSerializer` for details of the binary
+    format for tuples.
   */
   record TupleDeserializer {
     @chpldoc.nodoc
@@ -4112,21 +4133,22 @@ record binaryDeserializer {
   }
 
   /*
-    Start deserializing a list by returning a ``ListDeserializer``.
+    Start deserializing a list by returning a :record:`ListDeserializer`.
 
-    :arg reader: The ``fileReader`` to use when deserializing.
+    :arg reader: The :record:`fileReader` to use when deserializing.
 
-    :returns: A new :type:`ListDeserializer`
+    :returns: A new :record:`ListDeserializer`
   */
   proc startList(reader: fileReader(?)) throws {
     return new ListDeserializer(reader, reader.read(uint));
   }
 
   /*
-    Returned by ``startList`` to provide the API for deserializing lists.
+    Returned by :proc:`~IO.binaryDeserializer.startList` to provide the API for
+    deserializing lists.
 
-    See ``binarySerializer.ListSerializer`` for details of the binary format
-    for lists.
+    See :record:`binarySerializer.ListSerializer` for details of the binary
+    format for lists.
   */
   record ListDeserializer {
     @chpldoc.nodoc
@@ -4163,7 +4185,7 @@ record binaryDeserializer {
     /*
       End deserialization of the current list.
 
-      :throws: A ``BadFormatError`` if there are remaining elements.
+      :throws: A :type:`~OS.BadFormatError` if there are remaining elements.
     */
     proc endList() throws {
       if _numElements != 0 then
@@ -4179,21 +4201,22 @@ record binaryDeserializer {
   }
 
   /*
-    Start deserializing an array by returning an ``ArrayDeserializer``.
+    Start deserializing an array by returning an :record:`ArrayDeserializer`.
 
-    :arg reader: The ``fileReader`` to use when deserializing.
+    :arg reader: The :record:`fileReader` to use when deserializing.
 
-    :returns: A new :type:`ArrayDeserializer`
+    :returns: A new :record:`ArrayDeserializer`
   */
   proc startArray(reader: fileReader(?)) throws {
     return new ArrayDeserializer(reader, endian);
   }
 
   /*
-    Returned by ``startArray`` to provide the API for deserializing arrays.
+    Returned by :proc:`~IO.binaryDeserializer.startArray` to provide the API for
+    deserializing arrays.
 
-    See ``binarySerializer.ArraySerializer`` for details of the binary format
-    for arrays.
+    See :record:`binarySerializer.ArraySerializer` for details of the binary
+    format for arrays.
   */
   record ArrayDeserializer {
     @chpldoc.nodoc
@@ -4202,7 +4225,8 @@ record binaryDeserializer {
     const endian : endianness;
 
     /*
-      Inform the ``ArrayDeserializer`` to start deserializing a new dimension.
+      Inform the :record:`~IO.binaryDeserializer.ArrayDeserializer` to start
+      deserializing a new dimension.
     */
     proc startDim() throws {
     }
@@ -4240,7 +4264,8 @@ record binaryDeserializer {
       .. note::
 
         This method is only optimized for the case where the
-        ``binaryDeserializer`` has been configured for ``native`` endianness.
+        :record:`binaryDeserializer` has been configured for ``native``
+        endianness.
 
       .. warning::
 
@@ -4279,7 +4304,7 @@ record binaryDeserializer {
   /*
     Start deserializing a map by returning a ``MapDeserializer``.
 
-    :arg reader: The ``fileReader`` to use when deserializing.
+    :arg reader: The :record:`fileReader` to use when deserializing.
 
     :returns: A new :type:`MapDeserializer`
   */
@@ -4288,9 +4313,10 @@ record binaryDeserializer {
   }
 
   /*
-    Returned by ``startMap`` to provide the API for deserializing maps.
+    Returned by :proc:`~IO.binaryDeserializer.startMap` to provide the API for
+    deserializing maps.
 
-    See ``binarySerializer.MapSerializer`` for details of the binary
+    See :record:`binarySerializer.MapSerializer` for details of the binary
     format for map.
   */
   record MapDeserializer {
@@ -4340,7 +4366,7 @@ record binaryDeserializer {
     /*
       End deserialization of the current map.
 
-      :throws: A ``BadFormatError`` if there are entries remaining.
+      :throws: A :type:`~OS.BadFormatError` if there are entries remaining.
     */
     proc endMap() throws {
       if _numElements != 0 then
@@ -4352,8 +4378,8 @@ record binaryDeserializer {
 
       .. warning::
 
-        Behavior of 'hasMore' is undefined when called between ``readKey`` and
-        ``readValue``.
+        Behavior of 'hasMore' is undefined when called between :proc:`readKey`
+        and :proc:`readValue`.
     */
     proc hasMore() : bool throws {
       return _numElements > 0;
@@ -4534,13 +4560,14 @@ proc ref fileWriter.deinit() {
 }
 
 /*
-  Create and return an alias of this ``fileReader`` configured to use
+  Create and return an alias of this :record:`fileReader` configured to use
   ``deserializerType`` for deserialization. The provided ``deserializerType``
   must be able to be default-initialized.
 
   .. warning::
 
-    It is an error for the returned alias to outlive the original ``fileReader``.
+    It is an error for the returned alias to outlive the original
+    :record:`fileReader`.
 */
 proc fileReader.withDeserializer(type deserializerType) :
   fileReader(this.locking, deserializerType) {
@@ -4549,12 +4576,13 @@ proc fileReader.withDeserializer(type deserializerType) :
 }
 
 /*
-  Create and return an alias of this ``fileReader`` configured to use
+  Create and return an alias of this :record:`fileReader` configured to use
   ``deserializer`` for deserialization.
 
   .. warning::
 
-    It is an error for the returned alias to outlive the original ``fileReader``.
+    It is an error for the returned alias to outlive the original
+    :record:`fileReader`.
 */
 proc fileReader.withDeserializer(in deserializer: ?dt) : fileReader(this.locking, dt) {
   var ret = new fileReader(this.locking, dt);
@@ -4569,13 +4597,14 @@ proc fileReader.withDeserializer(in deserializer: ?dt) : fileReader(this.locking
 }
 
 /*
-  Create and return an alias of this ``fileWriter`` configured to use
+  Create and return an alias of this :record:`fileWriter` configured to use
   ``serializerType`` for serialization. The provided ``serializerType`` must be
   able to be default-initialized.
 
   .. warning::
 
-    It is an error for the returned alias to outlive the original ``fileWriter``.
+    It is an error for the returned alias to outlive the original
+    :record:`fileWriter`.
 */
 proc fileWriter.withSerializer(type serializerType) :
   fileWriter(this.locking, serializerType) {
@@ -4584,12 +4613,13 @@ proc fileWriter.withSerializer(type serializerType) :
 }
 
 /*
-  Create and return an alias of this ``fileWriter`` configured to use
+  Create and return an alias of this :record:`fileWriter` configured to use
   ``serializer`` for serialization.
 
   .. warning::
 
-    It is an error for the returned alias to outlive the original ``fileWriter``.
+    It is an error for the returned alias to outlive the original
+    :record:`fileWriter`.
 */
 proc fileWriter.withSerializer(in serializer: ?st) : fileWriter(this.locking, st) {
   var ret = new fileWriter(this.locking, st);
@@ -4888,7 +4918,7 @@ inline proc fileWriter.unlock() {
 config param fileOffsetWithoutLocking = false;
 
 /*
-   Return the current offset of a fileReader.
+   Return the current offset of a :record:`fileReader`.
 
    If the fileReader can be used by multiple tasks, take care when doing
    operations that rely on the fileReader's current offset. To prevent race
@@ -4905,7 +4935,7 @@ proc fileReader.offset(): int(64) {
 }
 
 /*
-   Return the current offset of a fileWriter.
+   Return the current offset of a :record:`fileWriter`.
 
    If the fileWriter can be used by multiple tasks, take care when doing
    operations that rely on the fileWriter's current offset. To prevent race
@@ -4988,7 +5018,7 @@ proc fileWriter.advance(amount:int(64)) throws {
 }
 
 /*
-   Read until a separator is found, leaving the ``fileReader`` offset just
+   Read until a separator is found, leaving the :record:`fileReader` offset just
    after it.
 
    If the separator cannot be found, the ``fileReader`` offset is left at EOF
@@ -5039,10 +5069,11 @@ proc fileReader.advanceThrough(separator: ?t) throws where t==string || t==bytes
 }
 
 /*
-   Read until a separator is found, leaving the ``fileReader`` offset just before it.
+   Read until a separator is found, leaving the :record:`fileReader` offset just
+   before it.
 
-   If the separator cannot be found, the ``fileReader`` offset is left at EOF and an
-   ``UnexpectedEofError`` is thrown.
+   If the separator cannot be found, the ``fileReader`` offset is left at EOF
+   and an ``UnexpectedEofError`` is thrown.
 
    .. note::
 
@@ -5573,7 +5604,7 @@ private proc openReaderHelper(path:string,
 }
 
 /*
-  Create a :record:`fileReader` around a :type:`string`
+  Create a :record:`fileReader` around a :type:`~String.string`
 
   Note that the string is copied into a local memory file, so it can be modified
   after the ``fileReader`` is created without affecting the contents of the
@@ -5606,7 +5637,7 @@ proc openStringReader(const s: string, in deserializer: ?dt = defaultSerializeVa
 }
 
 /*
-  Create a :record:`fileReader` around a :type:`bytes`
+  Create a :record:`fileReader` around a :type:`~Bytes.bytes`
 
   Note that the bytes is copied into a local memory file, so it can be modified
   after the ``fileReader`` is created without affecting the contents of the
@@ -6657,8 +6688,8 @@ inline proc fileReader._readLiteralCommon(x:?t, ignore:bool,
 }
 
 /*
-  Advances the offset of a ``fileReader`` within the file by reading the exact
-  text of the given string ``literal`` from the fileReader.
+  Advances the offset of a :record:`fileReader` within the file by reading the
+  exact text of the given string ``literal`` from the fileReader.
 
   If the string is not matched exactly, then the fileReader's offset is
   unchanged. In such cases a :class:`OS.BadFormatError` will be thrown, unless
@@ -6684,7 +6715,7 @@ proc fileReader.readLiteral(literal:string,
 
 /*
   Advances the offset of a fileReader by reading the exact bytes of the given
-  ``literal`` from the ``fileReader``.
+  ``literal`` from the :record:`fileReader`.
 
   If the bytes are not matched exactly, then the fileReader's offset is
   unchanged. In such cases a :class:`OS.BadFormatError` will be thrown, unless
@@ -6735,7 +6766,7 @@ inline proc fileReader._readNewline() : void throws {
 
 // TODO: How does this differ from readln() ?
 /*
-  Advances the offset of the fileReader by reading a newline.
+  Advances the offset of the :record:`fileReader` by reading a newline.
 
   If a newline is not matched exactly, then the fileReader's offset is
   unchanged. In such cases a :class:`OS.BadFormatError` will be thrown, unless
@@ -6766,8 +6797,8 @@ proc fileReader._matchLiteralCommon(literal, ignore : bool) : bool throws {
 }
 
 /*
-  Advances the offset of a fileReader by reading the exact text of the given
-  string ``literal`` from the fileReader.
+  Advances the offset of a :record:`fileReader` by reading the exact text of the
+  given string ``literal`` from the fileReader.
 
   If the string is not matched exactly, then the fileReader's offset is
   unchanged and this method will return ``false``. In other words, this
@@ -6792,8 +6823,8 @@ proc fileReader.matchLiteral(literal:string,
 }
 
 /*
-  Advances the offset of a ``fileReader`` by reading the exact bytes of the
-  given ``literal`` from the ``fileReader``.
+  Advances the offset of a :record:`fileReader` by reading the exact bytes of
+  the given ``literal`` from the ``fileReader``.
 
   If the bytes are not matched exactly, then the fileReader's offset is
   unchanged and this method will return ``false``. In other words, this
@@ -6818,7 +6849,7 @@ proc fileReader.matchLiteral(literal:bytes,
 }
 
 /*
-  Advances the offset of the ``fileReader`` by reading a newline.
+  Advances the offset of the :record:`fileReader` by reading a newline.
 
   If a newline is not matched exactly, then the fileReader's offset is
   unchanged and this method will return ``false``. In other words, this
@@ -6861,8 +6892,8 @@ proc fileWriter._writeLiteralCommon(x:?t) : void throws {
 }
 
 /*
-  Writes a string to the ``fileWriter``, ignoring any formatting configured for
-  this ``fileWriter``.
+  Writes a string to the :record:`fileWriter`, ignoring any formatting
+  configured for this ``fileWriter``.
 */
 inline
 proc fileWriter.writeLiteral(literal:string) : void throws {
@@ -6870,8 +6901,8 @@ proc fileWriter.writeLiteral(literal:string) : void throws {
 }
 
 /*
-  Writes bytes to the ``fileWriter``, ignoring any formatting configured for this
-  ``fileWriter``.
+  Writes bytes to the :record:`fileWriter`, ignoring any formatting configured
+  for this ``fileWriter``.
 */
 inline
 proc fileWriter.writeLiteral(literal:bytes) : void throws {
@@ -6880,8 +6911,8 @@ proc fileWriter.writeLiteral(literal:bytes) : void throws {
 
 // TODO: How does this differ from writeln() ?
 /*
-  Writes a newline to the ``fileWriter``, ignoring any formatting configured for
-  this ``fileWriter``.
+  Writes a newline to the :record:`fileWriter`, ignoring any formatting
+  configured for this ``fileWriter``.
 */
 inline
 proc fileWriter.writeNewline() : void throws {
@@ -6931,7 +6962,7 @@ proc fileWriter.styleElement(element:int):int {
 }
 
 /*
-  Iterate over all of the lines ending in ``\n`` in a fileReader - the
+  Iterate over all of the lines ending in ``\n`` in a :record:`fileReader` - the
   fileReader lock will be held while iterating over the lines.
 
   Only serial iteration is supported. This iterator will halt on internal
@@ -7055,13 +7086,13 @@ inline proc fileReader._readInner(ref args ...?k):void throws {
 }
 
 /*
-   Read one or more values from a ``fileReader``. The ``fileReader``'s lock
-   will be held while reading the values — this protects against interleaved
-   reads.
+   Read one or more values from a :record:`fileReader`. The ``fileReader``'s
+   lock will be held while reading the values — this protects against
+   interleaved reads.
 
    :arg args: a series of variables to read into. Basic types are handled
               internally, but for other types this function will call
-              value.readThis() with a ``Reader`` argument as described
+              value.deserialize() with a `fileReader` argument as described
               in :ref:`serialize-deserialize`.
    :returns: `true` if the read succeeded, and `false` on end of file.
 
@@ -7082,8 +7113,8 @@ inline proc fileReader.read(ref args ...?k):bool throws {
 /*
   Read a line into an array of bytes.
 
-  Reads bytes from the ``fileReader`` until a ``\n`` is reached. Values are
-  read in binary format (i.e., this method is not aware of UTF-8 encoding).
+  Reads bytes from the :record:`fileReader` until a ``\n`` is reached. Values
+  are read in binary format (i.e., this method is not aware of UTF-8 encoding).
 
   The array's size is not changed to accommodate bytes. If a newline is not
   found before the array is filled, or ``maxSize`` bytes are read, a
@@ -7226,7 +7257,7 @@ proc readStringBytesData(ref s: ?t /*: string or bytes*/,
 }
 
 /*
-  Read a line into a ``string``. Reads until a ``\n`` is reached.
+  Read a line into a :type:`~String.string`. Reads until a ``\n`` is reached.
 
   :arg s: the :type:`~String.string` to read into. Contents are overwritten.
   :arg maxSize: The maximum number of codepoints to store into ``s``. The
@@ -7235,7 +7266,7 @@ proc readStringBytesData(ref s: ?t /*: string or bytes*/,
   :returns: ``true`` if a line was read without error, ``false`` upon EOF
 
   :throws BadFormatError: If the line is longer than `maxSize`. The
-                          ``fileReader`` offset is not moved.
+                          :record:`fileReader` offset is not moved.
   :throws SystemError: If data could not be read from the ``fileReader``
                        due to a :ref:`system error<io-general-sys-error>`.
 */
@@ -7313,7 +7344,7 @@ proc fileReader.readLine(ref s: string,
 }
 
 /*
-  Read a line into a ``bytes``. Reads until a ``\n`` is reached.
+  Read a line into a :type:`~Bytes.bytes`. Reads until a ``\n`` is reached.
 
   :arg b: the :type:`~Bytes.bytes` to receive the line. Contents are overwritten.
   :arg maxSize: The maximum number of bytes to store into ``b``. The default of
@@ -7323,7 +7354,7 @@ proc fileReader.readLine(ref s: string,
 
   :throws BadFormatError: If the line is longer than `maxSize`. The file
                           offset is not moved.
-  :throws SystemError: If data could not be read from the ``fileReader``
+  :throws SystemError: If data could not be read from the :record:`fileReader`
                        due to a :ref:`system error<io-general-sys-error>`.
 */
 proc fileReader.readLine(ref b: bytes,
@@ -7409,8 +7440,8 @@ proc fileReader.readLine(ref b: bytes,
   :arg maxSize: The maximum number of codepoints to read. The default of -1
                 means to read an unlimited number of codepoints.
   :arg stripNewline: Whether to strip the trailing ``\n`` from the line.
-  :returns: A ``string`` or ``bytes`` with the contents of the ``fileReader``
-            up to (and possibly including) the newline.
+  :returns: A ``string`` or ``bytes`` with the contents of the
+            :record:`fileReader` up to (and possibly including) the newline.
 
   :throws EofError: If nothing could be read because the ``fileReader``
                     was already at EOF.
@@ -7430,11 +7461,11 @@ proc fileReader.readLine(type t=string, maxSize=-1,
 
 /*
   Read until the given separator is found, returning the contents of the
-  ``fileReader`` through that point.
+  :record:`fileReader` through that point.
 
   If the separator is found, the ``fileReader`` offset is left immediately
   after it. If the separator could not be found in the next ``maxSize`` bytes,
-  a ``BadFormatError`` is thrown and the ``fileReader``'s offset is not
+  a :type:`~OS.BadFormatError` is thrown and the ``fileReader``'s offset is not
   changed. Otherwise, if EOF is reached before finding the separator, the
   remainder of the ``fileReader``'s contents are returned and the offset is
   left at EOF.
@@ -7471,7 +7502,7 @@ proc fileReader.readThrough(separator: ?t, maxSize=-1, stripSeparator=false): t
 
 /*
   Read until the given separator is found, returning the contents of the
-  ``fileReader`` through that point.
+  :record:`fileReader` through that point.
 
   See the above :proc:`overload <fileReader.readThrough>` of this method for
   more details.
@@ -7530,7 +7561,7 @@ proc fileReader.readThrough(separator: string, ref s: string, maxSize=-1, stripS
 
 /*
   Read until the given separator is found, returning the contents of the
-  ``fileReader`` through that point.
+  :record:`fileReader` through that point.
 
   See the above :proc:`overload <fileReader.readThrough>` of this method for
   more details.
@@ -7573,11 +7604,11 @@ proc fileReader.readThrough(separator: bytes, ref b: bytes, maxSize=-1, stripSep
 
 /*
   Read until the given separator is found, returning the contents of the
-  ``fileReader`` up to that point.
+  :record:`fileReader` up to that point.
 
   If the separator is found, the ``fileReader`` offset is left immediately
   before it. If the separator could not be found in the next ``maxSize`` bytes,
-  a ``BadFormatError`` is thrown and the ``fileReader``'s offset is not
+  a :type:`~OS.BadFormatError` is thrown and the ``fileReader``'s offset is not
   changed. Otherwise, if EOF is reached before finding the separator, the
   remainder of the ``fileReader``'s contents are returned and the offset is
   left at EOF.
@@ -7613,7 +7644,7 @@ proc fileReader.readTo(separator: ?t, maxSize=-1): t throws
 
 /*
   Read until the given separator is found, returning the contents of the
-  ``fileReader`` up to that point.
+  :record:`fileReader` up to that point.
 
   See the above :proc:`overload <fileReader.readTo>` of this method for
   more details.
@@ -7664,7 +7695,7 @@ proc fileReader.readTo(separator: string, ref s: string, maxSize=-1): bool throw
 
 /*
   Read until the given separator is found, returning the contents of the
-  ``fileReader`` up to that point.
+  :record:`fileReader` up to that point.
 
   See the above :proc:`overload <fileReader.readTo>` of this method for
   more details.
@@ -7796,8 +7827,8 @@ private proc _findSeparator(separator: ?t, maxBytes=-1, ch_internal): (errorCode
 
 
 /*
-  Read the remaining contents of the fileReader into an instance of the
-  specified type
+  Read the remaining contents of the :record:`fileReader` into an instance of
+  the specified type
 
   :arg t: the type to read into; must be :type:`~String.string` or
           :type:`~Bytes.bytes`. Defaults to ``bytes`` if not specified.
@@ -7827,7 +7858,7 @@ proc fileReader.readAll(type t=bytes): t throws
 }
 
 /*
-  Read the remaining contents of the ``fileReader`` into a ``string``.
+  Read the remaining contents of the :record:`fileReader` into a ``string``.
 
   Note that any existing contents of the ``string`` are overwritten.
 
@@ -7850,7 +7881,7 @@ proc fileReader.readAll(ref s: string): int throws {
 }
 
 /*
-  Read the remaining contents of the ``fileReader`` into a ``bytes``.
+  Read the remaining contents of the :record:`fileReader` into a ``bytes``.
 
   Note that any existing contents of the ``bytes`` are overwritten.
 
@@ -7873,7 +7904,8 @@ proc fileReader.readAll(ref b: bytes): int throws {
 }
 
 /*
-  Read the remaining contents of the ``fileReader`` into an array of bytes.
+  Read the remaining contents of the :record:`fileReader` into an array of
+  bytes.
 
   Note that this routine currently requires a 1D rectangular non-strided array.
 
@@ -7943,7 +7975,7 @@ proc fileReader.readAll(ref a: [?d] ?t): int throws
 }
 
 /*
-  Read a given number of codepoints from a ``fileReader``, returning a new
+  Read a given number of codepoints from a :record:`fileReader`, returning a new
   :type:`~String.string`.
 
   The ``string``'s length may be less than ``maxSize`` if EOF is reached while
@@ -7969,7 +8001,7 @@ proc fileReader.readString(maxSize: int): string throws {
 }
 
 /*
-  Read a given number of codepoints from a ``fileReader`` into a
+  Read a given number of codepoints from a :record:`fileReader` into a
   :type:`~String.string`.
 
   The updated ``string``'s length may be less than ``maxSize`` if EOF is
@@ -7993,7 +8025,7 @@ proc fileReader.readString(ref s: string, maxSize: int): bool throws {
 }
 
 /*
-  Read a given number of bytes from a ``fileReader``, returning a new
+  Read a given number of bytes from a :record:`fileReader`, returning a new
   :type:`~Bytes.bytes`.
 
   The ``bytes``'s length may be less than ``maxSize`` if EOF is reached while
@@ -8019,7 +8051,7 @@ proc fileReader.readBytes(maxSize: int): bytes throws {
 }
 
 /*
-  Read a given number of bytes from a ``fileReader`` into a
+  Read a given number of bytes from a :record:`fileReader` into a
   :type:`~Bytes.bytes`.
 
   The updated ``bytes``'s length may be less than ``maxSize`` if EOF is
@@ -8105,7 +8137,7 @@ private proc readBytesOrString(ch: fileReader, ref out_var: ?t, len: int(64)) :
            least-significant bits set.
    :arg numBits: how many bits to read
    :returns: ``true`` if the bits were read, and ``false`` otherwise (i.e., the
-             ``fileReader`` was already at EOF).
+             :record:`fileReader` was already at EOF).
 
    :throws UnexpectedEofError: If EOF was encountered before ``numBits``
                                could be read.
@@ -8138,7 +8170,7 @@ proc fileReader.readBits(ref x:integral, numBits:int):bool throws {
     :returns: bits read. This value will have its *numBits* least-significant
               bits set
 
-    :throws EofError: If the ``fileReader`` offset was already at EOF.
+    :throws EofError: If the :record:`fileReader` offset was already at EOF.
     :throws UnexpectedEofError: If EOF was encountered before ``numBits``
                                 could be read.
     :throws SystemError: If data could not be read from the ``fileReader``
@@ -8157,7 +8189,7 @@ proc fileReader.readBits(type resultType, numBits:int):resultType throws {
   :arg x: a value containing *numBits* bits to write the least-significant bits
   :arg numBits: how many bits to write
 
-  :throws EofError: If the ``fileWriter`` offset was already at EOF.
+  :throws EofError: If the :record:`fileWriter` offset was already at EOF.
   :throws UnexpectedEofError: If the write operation exceeds the
                               ``fileWriter``'s specified range.
   :throws IllegalArgumentError: If writing more bits than fit into `x`.
@@ -8180,7 +8212,7 @@ proc fileWriter.writeBits(x: integral, numBits: int) : void throws {
 }
 
 /*
-  Write a single Unicode codepoint to a ``fileWriter``
+  Write a single Unicode codepoint to a :record:`fileWriter`
 
   :arg codepoint: Unicode codepoint to write
 
@@ -8195,7 +8227,7 @@ proc fileWriter.writeCodepoint(codepoint: int) throws {
 }
 
 /*
-  Read a single Unicode codepoint from a ``fileReader``
+  Read a single Unicode codepoint from a :record:`fileReader`
 
   :returns: Unicode codepoint read
 
@@ -8213,7 +8245,7 @@ proc fileReader.readCodepoint(): int throws {
 }
 
 /*
-  Read a single Unicode codepoint from a ``fileReader``
+  Read a single Unicode codepoint from a :record:`fileReader`
 
   :arg codepoint: where to store the read codepoint
   :returns: ``true`` if the codepoint was read, and ``false`` otherwise (i.e.,
@@ -8232,7 +8264,7 @@ proc fileReader.readCodepoint(ref codepoint: int):bool throws {
 }
 
 /*
-  Write a single byte to a ``fileWriter``
+  Write a single byte to a :record:`fileWriter`
 
   :arg byte: the byte to write
 
@@ -8258,7 +8290,7 @@ proc fileWriter.writeByte(byte: uint(8)) throws {
 }
 
 /*
-  Read a single byte from a ``fileReader``
+  Read a single byte from a :record:`fileReader`
 
   :returns: the byte read
 
@@ -8274,7 +8306,7 @@ proc fileReader.readByte(): uint(8) throws {
 }
 
 /*
-  Read a single byte from a ``fileReader``
+  Read a single byte from a :record:`fileReader`
 
   :arg byte: where to store the read byte
   :returns: ``true`` if the byte was read, and ``false`` otherwise (i.e.,
@@ -8327,7 +8359,8 @@ if !IOSkipBufferingForLargeOps {
 }
 
 /*
-  Write ``size`` codepoints from a :type:`~String.string` to a ``fileWriter``
+  Write ``size`` codepoints from a :type:`~String.string` to a
+  :record:`fileWriter`
 
   :arg s: the ``string`` to write
   :arg size: the number of codepoints to write from the ``string``
@@ -8346,7 +8379,7 @@ proc fileWriter.writeString(s: string, size = s.size) throws {
 }
 
 /*
-  Write ``size`` bytes from a :type:`~Bytes.bytes` to a ``fileWriter``
+  Write ``size`` bytes from a :type:`~Bytes.bytes` to a :record:`fileWriter`
 
   :arg b: the ``bytes`` to write
   :arg size: the number of bytes to write from the ``bytes``
@@ -8387,7 +8420,8 @@ private proc endianToIoKind(param e: endianness) param {
 }
 
 /*
-  Write ``numBytes`` of data from a :class:`~CTypes.c_ptr` to a ``fileWriter``
+  Write ``numBytes`` of data from a :class:`~CTypes.c_ptr` to a
+  :record:`fileWriter`
 
   Note that native endianness is always used.
 
@@ -8422,7 +8456,8 @@ proc fileWriter.writeBinary(ptr: c_ptr(?t), numBytes: int) throws
 }
 
 /*
-  Write ``numBytes`` of data from a ``CTypes.c_ptr(void)`` to a ``fileWriter``
+  Write ``numBytes`` of data from a ``CTypes.c_ptr(void)`` to a
+  :record:`fileWriter`
 
   The data are written to the file one byte at a time.
 
@@ -8449,7 +8484,7 @@ proc fileWriter.writeBinary(ptr: c_ptr(void), numBytes: int) throws {
 }
 
 /*
-  Write a binary number to the ``fileWriter``
+  Write a binary number to the :record:`fileWriter`
 
   :arg arg: number to be written
   :arg endian: :type:`endianness` compile-time argument that specifies the byte
@@ -8473,7 +8508,7 @@ proc fileWriter.writeBinary(arg:numeric,
 }
 
 /*
-  Write a binary number to the ``fileWriter``
+  Write a binary number to the :record:`fileWriter`
 
   :arg arg: number to be written
   :arg endian: :type:`endianness` specifies the byte order in which
@@ -8500,7 +8535,7 @@ proc fileWriter.writeBinary(arg:numeric, endian:endianness) throws {
 }
 
 /*
-  Write a :type:`~String.string` to a ``fileWriter`` in binary format
+  Write a :type:`~String.string` to a :record:`fileWriter` in binary format
 
   :arg s: the ``string`` to write
   :arg size: the number of codepoints to write from the ``string``
@@ -8548,7 +8583,7 @@ proc fileWriter.writeBinary(s: string, size: int = s.size) throws {
 }
 
 /*
-  Write a :type:`~Bytes.bytes` to a ``fileWriter`` in binary format
+  Write a :type:`~Bytes.bytes` to a :record:`fileWriter` in binary format
 
   :arg b: the ``bytes`` to write
   :arg size: the number of bytes to write from the ``bytes``
@@ -8588,9 +8623,10 @@ private proc isSuitableForBinaryReadWrite(arr: _array) param {
 }
 
 /*
-  Write an array of binary numbers to a ``fileWriter``
+  Write an array of binary numbers to a :record:`fileWriter`
 
-  Note that this routine currently requires a local rectangular non-strided array.
+  Note that this routine currently requires a local rectangular non-strided
+  array.
 
   :arg data: an array of numbers to write to the fileWriter
   :arg endian: :type:`endianness` compile-time argument that specifies the byte
@@ -8648,7 +8684,7 @@ proc fileWriter.writeBinary(const ref data: [?d] ?t, param endian:endianness = e
 
 
 /*
-  Write an array of binary numbers to a ``fileWriter``
+  Write an array of binary numbers to a :record:`fileWriter`
 
   Note that this routine currently requires a local rectangular non-strided array.
 
@@ -8686,7 +8722,7 @@ proc fileWriter.writeBinary(const ref data: [] ?t, endian:endianness) throws
 }
 
 /*
-  Read a binary number from the ``fileReader``
+  Read a binary number from the :record:`fileReader`
 
   :arg arg: number to be read
   :arg endian: :type:`endianness` compile-time argument that specifies the byte
@@ -8714,7 +8750,7 @@ proc fileReader.readBinary(ref arg:numeric, param endian:endianness = endianness
 }
 
 /*
-  Read a binary number from the ``fileReader``
+  Read a binary number from the :record:`fileReader`
 
   :arg arg: number to be read
   :arg endian: :type:`endianness` specifies the byte order in which
@@ -8748,9 +8784,9 @@ proc fileReader.readBinary(ref arg:numeric, endian: endianness):bool throws {
   Read a specified number of codepoints into a :type:`~String.string`
 
   The resulting string ``s`` may be smaller than ``maxSize`` if EOF is reached
-  before reading the specified number of codepoints. Additionally, if nothing
-  is read from the fileReader, ``s`` will be set to ``""`` (the empty string)
-  and the method will return ``false``.
+  before reading the specified number of codepoints. Additionally, if nothing is
+  read from the :record:`fileReader`, ``s`` will be set to ``""`` (the empty
+  string) and the method will return ``false``.
 
   .. note::
 
@@ -8792,8 +8828,8 @@ proc fileReader.readBinary(ref s: string, maxSize: int): bool throws {
   Read a specified number of bytes into a :type:`~Bytes.bytes`
 
   The bytes ``b`` may be smaller than ``maxSize`` if EOF is reached before
-  reading the specified number of bytes. Additionally, if nothing is read
-  from the fileReader, ``b`` will be set to ``b""`` (the empty bytes) and
+  reading the specified number of bytes. Additionally, if nothing is read from
+  the :record:`fileReader`, ``b`` will be set to ``b""`` (the empty bytes) and
   the method will return ``false``.
 
   :arg b: the bytes to read into — this value is overwritten
@@ -8833,7 +8869,7 @@ proc fileReader.readBinary(ref b: bytes, maxSize: int): bool throws {
 config param ReadBinaryArrayReturnInt = true;
 
 /*
-  Read an array of binary numbers from a ``fileReader``
+  Read an array of binary numbers from a :record:`fileReader`
 
   Binary values of the type ``data.eltType`` are consumed from the fileReader
   until ``data`` is full or EOF is reached.
@@ -8901,12 +8937,13 @@ proc fileReader.readBinary(ref data: [?d] ?t, param endian = endianness.native):
 }
 
 /*
-   Read an array of binary numbers from a ``fileReader``
+   Read an array of binary numbers from a :record:`fileReader`
 
    Binary values of the type ``data.eltType`` are consumed from the fileReader
    until ``data`` is full or EOF is reached.
 
-   Note that this routine currently requires a local rectangular non-strided array.
+   Note that this routine currently requires a local rectangular non-strided
+   array.
 
    :arg data: an array to read into – existing values are overwritten.
    :arg endian: :type:`endianness` specifies the byte order in which
@@ -8954,7 +8991,7 @@ proc fileReader.readBinary(ref data: [] ?t, param endian = endianness.native): b
 }
 
 /*
-   Read up to ``maxBytes`` bytes from a ``fileReader`` into a
+   Read up to ``maxBytes`` bytes from a :record:`fileReader` into a
    :class:`~CTypes.c_ptr`
 
    Note that native endianness is always used.
@@ -8986,7 +9023,7 @@ proc fileReader.readBinary(ptr: c_ptr(?t), maxBytes: int): int throws {
 }
 
 /*
-   Read up to ``maxBytes`` bytes from a ``fileReader`` into a
+   Read up to ``maxBytes`` bytes from a :record:`fileReader` into a
    ``CTypes.c_ptr(void)``
 
    Note that data are read from the file one byte at a time.
@@ -9022,14 +9059,14 @@ proc fileReader.readln():bool throws {
 }
 
 /*
-   Read values from a ``fileReader`` and then consume any bytes until
+   Read values from a :record:`fileReader` and then consume any bytes until
    newline is reached. The input will be consumed atomically - the
    fileReader lock will be held while reading all of the passed values.
 
    :arg args: a list of arguments to read. This routine can be called
               with zero or more such arguments. Basic types are handled
               internally, but for other types this function will call
-              value.readThis() with a ``Reader`` argument as described
+              value.deserialize() with a ``fileReader`` argument as described
               in :ref:`serialize-deserialize`.
    :returns: `true` if the read succeeded, and `false` upon end of file.
 
@@ -9057,7 +9094,7 @@ proc fileReader.readln(ref args ...?k):bool throws {
    :arg t: the type to read
    :returns: the value read
 
-   :throws EofError: If the ``fileReader`` is already at EOF.
+   :throws EofError: If the :record:`fileReader` is already at EOF.
    :throws UnexpectedEofError: If EOF was encountered before data could
                                be fully read.
    :throws SystemError: If data could not be read from the ``fileReader``
@@ -9109,7 +9146,7 @@ proc fileReader.read(type t) throws {
    :arg t: the type to read
    :returns: the value read
 
-   :throws EofError: If the ``fileReader`` is at already EOF.
+   :throws EofError: If the :record:`fileReader` is at already EOF.
    :throws UnexpectedEofError: If EOF was encountered before data could
                                be fully read.
    :throws SystemError: If data could not be read from the ``fileReader``
@@ -9130,7 +9167,7 @@ proc fileReader.readln(type t) throws {
    :arg t: more than one type to read
    :returns: a tuple of the read values
 
-   :throws EofError: If the ``fileReader`` is already at EOF.
+   :throws EofError: If the :record:`fileReader` is already at EOF.
    :throws UnexpectedEofError: If EOF was encountered before data could
                                be fully read.
    :throws SystemError: If data could not be read from the ``fileReader``
@@ -9146,8 +9183,8 @@ proc fileReader.readln(type t ...?numTypes) throws where numTypes > 1 {
 
 /*
    Read values of passed types and return a tuple containing the read values.
-   The ``fileReader``'s lock will be held while reading — this protects against
-   interleaved reads.
+   The :record:`fileReader`'s lock will be held while reading — this protects
+   against interleaved reads.
 
    :arg t: more than one type to read
    :returns: a tuple of the read values
@@ -9166,13 +9203,13 @@ proc fileReader.read(type t ...?numTypes) throws where numTypes > 1 {
 }
 
 /*
-   Write values to a ``fileWriter``. The output will be produced atomically -
-   the ``fileWriter`` lock will be held while writing all of the passed
-   values.
+   Write values to a :record:`fileWriter`. The output will be produced
+   atomically - the ``fileWriter`` lock will be held while writing all of the
+   passed values.
 
    :arg args: a list of arguments to write. Basic types are handled
               internally, but for other types this function will call
-              value.writeThis() with the ``fileWriter`` as an argument.
+              value.serialize() with the ``fileWriter`` as an argument.
 
    :throws EofError: If EOF is reached before all the arguments could be
                      written.
@@ -9207,14 +9244,14 @@ proc fileWriter.writeln() throws {
 
 /*
 
-   Write values to a ``fileWriter`` followed by a newline.  The output will be
-   produced atomically - the ``fileWriter`` lock will be held while writing all of
-   the passed values.
+   Write values to a :record:`fileWriter` followed by a newline.  The output
+   will be produced atomically - the ``fileWriter`` lock will be held while
+   writing all of the passed values.
 
    :arg args: a variable number of arguments to write. This method can be
               called with zero or more arguments. Basic types are handled
               internally, but for other types this function will call
-              value.writeThis() with the fileWriter as an argument.
+              value.serialize() with the fileWriter as an argument.
 
    :throws EofError: If EOF is reached before all the arguments
                      could be written.
@@ -9229,7 +9266,7 @@ proc fileWriter.writeln(const args ...?k) throws {
 
 /*
 
-  Makes all writes to the ``fileWriter``, if any, available to concurrent
+  Makes all writes to the :record:`fileWriter`, if any, available to concurrent
   viewers of its associated file, such as other fileWriters/fileReader or other
   applications accessing this file concurrently.
 
@@ -9259,8 +9296,8 @@ proc fileWriter.flush(out error:errorCode) {
   }
 }
 
-/* Assert that a ``fileReader`` has reached end-of-file and that there was no
-   error doing the read.
+/* Assert that a :record:`fileReader` has reached end-of-file and that there was
+   no error doing the read.
 */
 @unstable("'assertEOF' is unstable and may be removed or modified in a future release")
 proc fileReader.assertEOF(errStr: string = "- Not at EOF") {
@@ -9281,7 +9318,7 @@ proc fileReader.atEOF(): bool throws {
 }
 
 /*
-  Close a ``fileReader``
+  Close a :record:`fileReader`
 
   :throws SystemError: If the ``fileReader`` is not successfully closed.
 */
@@ -9298,7 +9335,7 @@ proc fileReader.close() throws {
 }
 
 /*
-  Close a ``fileWriter``. Implicitly performs the :proc:`fileWriter.flush`
+  Close a :record:`fileWriter`. Implicitly performs the :proc:`fileWriter.flush`
   operation (see :ref:`about-io-filereader-filewriter-synchronization`).
 
   :throws SystemError: If the ``fileWriter`` is not successfully closed.
@@ -9316,7 +9353,7 @@ proc fileWriter.close() throws {
 }
 
 /*
-   Return ``true`` if a fileReader is currently closed.
+   Return ``true`` if a :record:`fileReader` is currently closed.
  */
 proc fileReader.isClosed() : bool {
   var ret:bool;
@@ -9327,7 +9364,7 @@ proc fileReader.isClosed() : bool {
 }
 
 /*
-   Return ``true`` if a fileWriter is currently closed.
+   Return ``true`` if a :record:`fileWriter` is currently closed.
  */
 proc fileWriter.isClosed() : bool {
   var ret:bool;
@@ -9499,19 +9536,12 @@ example, one might do:
   // My favorite number is 7
 
 The following sections offer a tour through the conversions to illustrate the
-common cases. A more precise definition follows in the "Format String
-Syntax in Detail" section below.
+common cases. A more precise definition follows in the
+:ref:`about-io-formatted-io-in-detail` section below.
 
 In this file, we use "integral" to refer to the Chapel types int or uint and
 "floating-point" to refer to real, imaginary, or complex, of any bit width.
 
-.. warning::
-
-   Binary conversions are now deprecated. Binary numeric conversions have been
-   replaced by :proc:`IO.fileReader.readBinary` and
-   :proc:`IO.fileWriter.writeBinary`.  Replacements for binary string
-   conversions are under development.
-
 Formatted I/O for C Programmers
 +++++++++++++++++++++++++++++++
 
@@ -9535,12 +9565,12 @@ C         Chapel       Meaning
 ========  ===========  ==========================================
 
 Unlike in C, a value of the wrong type will be cast appropriately - so for
-example printing 2 (an ``int``)  with ``%.2dr`` will result in ``2.00``.  Note
-that ``%n`` and ``%?`` are equivalent to ``%r`` for real conversions and ``%i``
-for numeric conversions; so these are also equivalent to ``%i`` ``%d`` or
-``%g`` in C. Also note that Chapel format strings include many capabilities
-not available with C formatted I/O routines - including quoted strings,
-binary numbers, and complex numbers.
+example printing 2 (an ``int``) with ``%.2dr`` will result in ``2.00``.  Note
+that Chapel's ``%n`` and ``%?`` are equivalent to ``%r`` for real conversions
+and ``%i`` for numeric conversions; so these are also equivalent to ``%i``
+``%d`` or ``%g`` in C. Also note that Chapel format strings include many
+capabilities not available with C formatted I/O routines - including quoted
+strings, binary numbers, and complex numbers.
 
 
 Generic Numeric Conversions
@@ -9555,8 +9585,8 @@ Generic Numeric Conversions
   of the conversion specifier (6 in this example).  The output
   can be longer, when needed to accommodate the number.
 
-``%{##}``
-  integral value padded out to 2 digits. Also works with real, imaginary
+``%{#####}``
+  integral value padded out to 5 digits. Also works with real, imaginary
   or complex numbers by rounding them to integers. Numbers with more
   digits will take up more space instead of being truncated.
 
@@ -9566,7 +9596,7 @@ For example:
 
 .. code-block:: chapel
 
-  writef("|${#####}|\n", 2.0i);
+  writef("|%{#####}|\n", 2.0i);
        // outputs:
        //   |   2i|
 
@@ -9662,7 +9692,7 @@ Real Conversions
  as with ``%r`` but padded on the left to 6 columns (i.e., right-justified)
 ``%<6r``
  as with ``%r`` but padded on the right to 6 columns (i.e., left-justified)
-``%^r``
+``%^6r``
  as with ``%r`` but padded equally on the left and right to 6 columns (i.e., center-justified)
 ``%>6r``
  equivalent to ``%6r``
@@ -9714,9 +9744,9 @@ Complex and Imaginary Conversions
  print a and b 4 significant digits and pad the entire complex
  number out to 6 columns
 ``%dz``
- print a and b with ``%dr``
+ print a and b with ``%dr`` (using decimal notation)
 ``%ez``
- print a and b with ``%er``
+ print a and b with ``%er`` (using exponential notation)
 
 String and Bytes Conversions
 ++++++++++++++++++++++++++++
@@ -9787,8 +9817,8 @@ General Conversion
 ++++++++++++++++++
 
 ``%?``
-  Use the ``fileReader``/``fileWriter``'s associated serializer/deserializer to write
-  or read a value.
+  Use the :record:`~IO.fileWriter`/:record:`~IO.fileReader`'s associated
+  serializer/deserializer to write or read a value.
 
   For example, read and write a record in JSON format:
 
@@ -10002,17 +10032,22 @@ Going through each section for text conversions:
 
 [conversion type]
    ``n``
-    means type-based number, allowing width and precision
+    means type-based number, allowing width and precision (size is not
+    mandatory)
    ``i``
-    means integral conversion
+    means integral conversion. Note that the size is mandatory for binary
+    integral conversions
    ``u``
-    means unsigned integral conversion
+    means unsigned integral conversion. Note that the size is mandatory for
+    binary integral conversions
    ``r``
-    means real conversion (e.g. ``12.23``)
+    means real conversion (e.g. ``12.23``). Note that the size is mandatory for
+    binary real conversions
    ``m``
     means imaginary conversion with an ``i`` after it (e.g. ``12.23i``)
    ``z``
-    means complex conversion
+    means complex conversion. Note that the size is mandatory for binary complex
+    conversions
    ``s``
     means string conversion
    ``S``
@@ -10031,28 +10066,6 @@ Going through each section for text conversions:
     means a Unicode character - either the first character in a string
     or an integral character code
 
-[conversion type]
-   ``n``
-    means type-based number (size is not mandatory)
-   ``i``
-    means integral. Note that the size is mandatory for binary integral
-    conversions
-   ``u``
-    means unsigned integral. Note that the size is mandatory for binary
-    integral conversions
-   ``r``
-    means real. Note that the size is mandatory for binary real conversions
-   ``m``
-    works the same as ``r`` for binary conversions
-   ``z``
-    means complex. Note that the size is mandatory for binary complex
-    conversions
-   ``s``
-    means string
-   ``c``
-    means a Unicode character - either the first character in a string
-    or an integral character code
-
 
 .. _about-io-formatted-io-examples:
 
@@ -11638,7 +11651,7 @@ proc fileReader.readf(fmtStr:?t) throws
 proc readf(fmt:string, ref args ...?k):bool throws {
   return try stdin.readf(fmt, (...args));
 }
-// documented in string version
+// documented in varargs version
 @chpldoc.nodoc
 proc readf(fmt:string):bool throws {
   return try stdin.readf(fmt);
@@ -11880,7 +11893,7 @@ proc fileReader._extractMatch(m:regexMatch, ref arg:?t, ref error:errorCode)
 
 /*  Sets arg to the string of a match.
 
-    Assumes that the fileReader has been marked before where
+    Assumes that the :record:`~IO.fileReader` has been marked before where
     the captures are being returned. Will change the fileReader
     offset to just after the match. Will not do anything
     if error is set.
@@ -11983,11 +11996,11 @@ proc ref fileReader.search(re:regex(?)):regexMatch throws
   return ret;
 }
 
-/*  Search for an offset in the fileReader from the current offset matching the
-    passed regular expression, possibly pulling out capture groups. If there is
-    a match, leaves the fileReader offset at the beginning of the match. If
-    there is no match, the fileReader offset will be advanced to the end of the
-    fileReader (or end of the file).
+/* Search for an offset in the :record:`~IO.fileReader` from the current offset
+    matching the passed regular expression, possibly pulling out capture
+    groups. If there is a match, leaves the fileReader offset at the beginning
+    of the match. If there is no match, the fileReader offset will be advanced
+    to the end of the fileReader (or end of the file).
 
     Throws a SystemError if an error occurs.
 
@@ -12011,8 +12024,8 @@ proc ref fileReader.search(re:regex(?), ref captures ...?k): regexMatch throws
    Yields tuples of :record:`Regex.regexMatch` objects, the 1st is always
    the match for the whole pattern.
 
-   At the time each match is returned, the fileReader offset is at the start
-   of that match. Note though that you would have to use
+   At the time each match is returned, the :record:`~IO.fileReader` offset is at
+   the start of that match. Note though that you would have to use
    :proc:`IO.fileReader.advance` to get to the offset of a capture group.
 
    After yielding each match, advances to just after that
diff --git a/test/deprecated/IO/ioendian/ioendianUse.good b/test/deprecated/IO/ioendian/ioendianUse.good
index 5b849f2cdea7..9903c1a9409f 100644
--- a/test/deprecated/IO/ioendian/ioendianUse.good
+++ b/test/deprecated/IO/ioendian/ioendianUse.good
@@ -1,10 +1,10 @@
-ioendianUse.chpl:3: warning: :enum: ioendian is deprecated; please use :enum: endianness instead
-ioendianUse.chpl:5: warning: :enum: ioendian is deprecated; please use :enum: endianness instead
-ioendianUse.chpl:6: warning: :enum: ioendian is deprecated; please use :enum: endianness instead
-ioendianUse.chpl:7: warning: :enum: ioendian is deprecated; please use :enum: endianness instead
-ioendianUse.chpl:10: warning: :enum: ioendian is deprecated; please use :enum: endianness instead
-ioendianUse.chpl:11: warning: :enum: ioendian is deprecated; please use :enum: endianness instead
-ioendianUse.chpl:13: warning: :enum: ioendian is deprecated; please use :enum: endianness instead
-ioendianUse.chpl:14: warning: :enum: ioendian is deprecated; please use :enum: endianness instead
+ioendianUse.chpl:3: warning: ioendian is deprecated; please use endianness instead
+ioendianUse.chpl:5: warning: ioendian is deprecated; please use endianness instead
+ioendianUse.chpl:6: warning: ioendian is deprecated; please use endianness instead
+ioendianUse.chpl:7: warning: ioendian is deprecated; please use endianness instead
+ioendianUse.chpl:10: warning: ioendian is deprecated; please use endianness instead
+ioendianUse.chpl:11: warning: ioendian is deprecated; please use endianness instead
+ioendianUse.chpl:13: warning: ioendian is deprecated; please use endianness instead
+ioendianUse.chpl:14: warning: ioendian is deprecated; please use endianness instead
 little
 little
diff --git a/test/deprecated/IO/ioendian/readWriteBinary.good b/test/deprecated/IO/ioendian/readWriteBinary.good
index caf69d7ba45e..0e7c00e2a110 100644
--- a/test/deprecated/IO/ioendian/readWriteBinary.good
+++ b/test/deprecated/IO/ioendian/readWriteBinary.good
@@ -1,8 +1,8 @@
 readWriteBinary.chpl:6: In function 'writeout':
-readWriteBinary.chpl:7: warning: :enum: ioendian is deprecated; please use :enum: endianness instead
-readWriteBinary.chpl:8: warning: :enum: ioendian is deprecated; please use :enum: endianness instead
-readWriteBinary.chpl:9: warning: :enum: ioendian is deprecated; please use :enum: endianness instead
+readWriteBinary.chpl:7: warning: ioendian is deprecated; please use endianness instead
+readWriteBinary.chpl:8: warning: ioendian is deprecated; please use endianness instead
+readWriteBinary.chpl:9: warning: ioendian is deprecated; please use endianness instead
 readWriteBinary.chpl:12: In function 'readin':
-readWriteBinary.chpl:13: warning: :enum: ioendian is deprecated; please use :enum: endianness instead
-readWriteBinary.chpl:14: warning: :enum: ioendian is deprecated; please use :enum: endianness instead
-readWriteBinary.chpl:15: warning: :enum: ioendian is deprecated; please use :enum: endianness instead
+readWriteBinary.chpl:13: warning: ioendian is deprecated; please use endianness instead
+readWriteBinary.chpl:14: warning: ioendian is deprecated; please use endianness instead
+readWriteBinary.chpl:15: warning: ioendian is deprecated; please use endianness instead