Add serializer example to Subprocess module docs (chapel-lang#23469)

This PR adds an example of how to use serializers to achieve binary IO
with the subprocess module, as an alternative to the deprecated ``kind``
field.

This PR also adds some documentation to the overlooked
``withSerializer`` and ``withDeserializer`` methods.

[reviewed-by @DanilaFe]

modules/standard/IO.chpl

@@ -3831,15 +3831,29 @@ proc ref fileWriter.deinit() {
   }
 }
 
-// Convenience for forms like 'r.withDeserializer(defaultDeserializer)`
-@chpldoc.nodoc
+/*
+  Create and return an alias of this ``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``.
+*/
 proc fileReader.withDeserializer(type deserializerType) :
   fileReader(this._kind, this.locking, deserializerType) {
   var des : deserializerType;
   return withDeserializer(des);
 }
 
-@chpldoc.nodoc
+/*
+  Create and return an alias of this ``fileReader`` configured to use
+  ``deserializer`` for deserialization.
+
+  .. warning::
+
+    It is an error for the returned alias to outlive the original ``fileReader``.
+*/
 proc fileReader.withDeserializer(in deserializer: ?dt) : fileReader(this._kind, this.locking, dt) {
   var ret = new fileReader(this._kind, this.locking, dt);
   ret._deserializer = new shared _serializeWrapper(dt, deserializer);
@@ -3852,15 +3866,29 @@ proc fileReader.withDeserializer(in deserializer: ?dt) : fileReader(this._kind,
   return ret;
 }
 
-// Convenience for forms like 'w.withSerializer(defaultSerializer)`
-@chpldoc.nodoc
+/*
+  Create and return an alias of this ``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``.
+*/
 proc fileWriter.withSerializer(type serializerType) :
   fileWriter(this._kind, this.locking, serializerType) {
   var ser : serializerType;
   return withSerializer(ser);
 }
 
-@chpldoc.nodoc
+/*
+  Create and return an alias of this ``fileWriter`` configured to use
+  ``serializer`` for serialization.
+
+  .. warning::
+
+    It is an error for the returned alias to outlive the original ``fileWriter``.
+*/
 proc fileWriter.withSerializer(in serializer: ?st) : fileWriter(this._kind, this.locking, st) {
   var ret = new fileWriter(this._kind, this.locking, st);
   ret._serializer = new shared _serializeWrapper(st, serializer);

modules/standard/Subprocess.chpl

@@ -127,6 +127,49 @@ other task is consuming it.
   locale. In this circumstance, the program will halt with an error message.
   These scenarios do work when using GASNet instead of the ugni layer.
 
+The Deprecated 'kind' Field
+---------------------------
+
+Prior to the 1.32 release, configuring a :type:`subprocess` record to use
+binary IO required using the ``kind`` field (of type ``iokind``) to enable
+binary IO and set the desired endianness. The 1.32 release introduced
+:ref:`serializers<ioSerializers>`, and deprecated use of the ``iokind`` type in
+favor of using Serializers and Deserializers to configure a given
+:type:`~IO.fileWriter` or :type:`~IO.fileReader` for a desired format.
+
+Users may now create aliases of ``stdin`` and ``stdout`` with different
+serialization formatting by using the :proc:`~IO.fileWriter.withSerializer` and
+:proc:`~IO.fileReader.withDeserializer` methods. For example, consider the
+following program that writes the numbers ``1`` through ``10`` in binary to the
+``hexdump`` utility:
+
+.. code-block:: chapel
+
+  use IO, Subprocess;
+
+  var sub = spawn(["hexdump", "-C"], stdin=pipeStyle.pipe, stdout=pipeStyle.pipe);
+
+  // Use 'withSerializer' to create a binary-serializing alias of 'sub.stdin'
+  var bin = sub.stdin.withSerializer(binarySerializer);
+
+  for i in 1..10 do bin.write(i:uint(8));
+
+  sub.communicate();
+
+  var line : string;
+  while sub.stdout.readLine(line) do
+    write(line);
+
+This program prints:
+
+.. code-block:: text
+
+  00000000  01 02 03 04 05 06 07 08  09 0a                    |..........|
+  0000000a
+
+Please refer to :type:`~IO.binarySerializer` and :type:`~IO.binaryDeserializer`
+for more information on their supported format.
+
  */
 module Subprocess {
   public use IO;