attempt to mass-format some of these doccomments

Sources/PNG/ColorTargets/PNG.RGBA.swift

@@ -48,7 +48,7 @@ extension PNG.RGBA
     ///
     ///     The ``r``, ``g``, and ``b`` components will be set to `value`,
     ///     and the ``a`` component will be set to [`T`max`].
-    /// - value : T
+    /// -   Parameter value:
     ///     A gray value.
     /// ## ()
     @inlinable
@@ -63,9 +63,9 @@ extension PNG.RGBA
     ///
     ///     The ``r``, ``g``, and ``b`` components will be set to `value`,
     ///     and the ``a`` component will be set to `alpha`.
-    /// - value : T
+    /// -   Parameter value:
     ///     A gray value.
-    /// - alpha : T
+    /// -   Parameter alpha:
     ///     An alpha value.
     /// ## ()
     @inlinable
@@ -80,11 +80,11 @@ extension PNG.RGBA
     ///
     ///     The ``r``, ``g``, and ``b`` components will be set to `red`, `green`,
     ///     and `blue`, respectively. The ``a`` component will be set to [`T`max`].
-    /// - red : T
+    /// -   Parameter red:
     ///     A red value.
-    /// - green : T
+    /// -   Parameter green:
     ///     A green value.
-    /// - blue : T
+    /// -   Parameter blue:
     ///     A blue value.
     /// ## ()
     @inlinable
@@ -99,13 +99,13 @@ extension PNG.RGBA
     ///
     ///     The ``r``, ``g``, ``b``, and ``a`` components will be set to `red`,
     ///     `green`, `blue`, and `alpha` respectively.
-    /// - red : T
+    /// -   Parameter red:
     ///     A red value.
-    /// - green : T
+    /// -   Parameter green:
     ///     A green value.
-    /// - blue : T
+    /// -   Parameter blue:
     ///     A blue value.
-    /// - alpha : T
+    /// -   Parameter alpha:
     ///     An alpha value.
     /// ## ()
     @inlinable
@@ -124,7 +124,7 @@ extension PNG.RGBA
     ///
     ///     This function is equivalent to calling ``init(_:_:)`` with
     ///     the ``VA/v`` and ``VA/a`` components of `va`.
-    /// - va : VA<T>
+    /// -   Parameter va:
     ///     A grayscale-alpha color.
     @inlinable
     public
@@ -173,10 +173,10 @@ extension PNG.RGBA
     ///     on ``r``, ``g``, and ``b``, after scaling them to the range of `U`.
     ///     The returned components are then scaled back to the range of ``T``.
     ///     The rescaling operation also affects the ``a`` component.
-    /// - _ : U.Type
+    /// -   Parameter _:
     ///     The integer type to perform the premultiplications in. `U.bitWidth`
     ///     must be less than [`T`bitWidth`].
-    /// - -> : Self
+    /// -   Returns:
     ///     The premultiplied color.
     @inlinable
     public
@@ -224,10 +224,10 @@ extension PNG.RGBA
     ///     on ``r``, ``g``, and ``b``, after scaling them to the range of `U`.
     ///     The returned components are then scaled back to the range of ``T``.
     ///     The rescaling operation also affects the ``a`` component.
-    /// - _ : U.Type
+    /// -   Parameter _:
     ///     The integer type to perform the straightening in. `U.bitWidth`
     ///     must be less than [`T`bitWidth`].
-    /// - -> : Self
+    /// -   Returns:
     ///     The straightened color.
     @inlinable
     public
@@ -282,24 +282,24 @@ extension PNG.RGBA:PNG.Color
     ///     This function will apply chroma keys if present. The unpacked components
     ///     are scaled to fill the range of ``T``, according to the color depth
     ///     computed from the color `format`.
-    /// - interleaved : [Swift.UInt8]
+    /// -   Parameter interleaved:
     ///     An image data buffer. It is expected to be obtained from the
     ///     ``Data.Rectangular/storage`` property of a ``Data/Rectangular``
     ///     image.
-    /// - format : Format
+    /// -   Parameter format:
     ///     The color format associated with the given data buffer.
     ///     It is expected to be obtained from the the
     ///     [`(Data.Rectangular).layout``(Layout).format`] property of a
     ///     ``Data/Rectangular`` image.
-    /// - deindexer : ([(r:Swift.UInt8, g:Swift.UInt8, b:Swift.UInt8, a:Swift.UInt8)]) -> (Swift.Int) -> Aggregate
+    /// -   Parameter deindexer:
     ///     A function which uses the palette entries in the color `format` to
     ///     generate a dereferencing function. This function is only invoked
     ///     if the color `format` is an indexed format. Its palette aggregates
     ///     will be interpreted as (*red*, *green*, *blue*, *alpha*) quadruplets.
     ///
     ///     See the [indexed color tutorial](https://github.com/tayloraswift/swift-png/tree/master/examples#using-indexed-images)
     ///     for more about the semantics of this function.
-    /// - -> : [Self]
+    /// -   Returns:
     ///     An array of RGBA pixels. The pixels
     ///     appear in the same order as they do in the image data buffer.
     @_specialize(where T == UInt8)
@@ -435,23 +435,23 @@ extension PNG.RGBA:PNG.Color
     ///
     ///     The components in each RGBA pixel are assumed to fill the entire
     ///     range of ``T``.
-    /// - pixels : [Self]
+    /// -   Parameter pixels:
     ///     An array of RGBA pixels.
-    /// - format : Format
+    /// -   Parameter format:
     ///     The color format to pack the given pixels as in the returned data buffer.
     ///
     ///     When the library uses an implementation of this function to construct
     ///     a ``Data/Rectangular`` image, this color format will be stored in
     ///     its [`(Data.Rectangular).layout``(Layout).format`] property.
-    /// - indexer : ([(r:Swift.UInt8, g:Swift.UInt8, b:Swift.UInt8, a:Swift.UInt8)]) -> (Aggregate) -> Swift.Int
+    /// -   Parameter indexer:
     ///     A function which uses the palette entries in the color `format` to
     ///     generate a referencing function. This function will only be invoked
     ///     if the color `format` is an indexed format. Its palette aggregates
     ///     will be interpreted as (*red*, *green*, *blue*, *alpha*) quadruplets.
     ///
     ///     See the [indexed color tutorial](https://github.com/tayloraswift/swift-png/tree/master/examples#using-indexed-images)
     ///     for more about the semantics of this function.
-    /// - -> : [Swift.UInt8]
+    /// -   Returns:
     ///     An image data buffer. The packed samples in this buffer appear
     ///     in the same order as the pixels in the `pixels` array. (But not
     ///     necessarily in the same order within each individual pixel.)

Sources/PNG/ColorTargets/PNG.VA.swift

@@ -38,7 +38,7 @@ extension PNG.VA
     ///
     ///     The ``v`` component will be set to `value`,
     ///     and the ``a`` component will be set to [`T`max`].
-    /// - value : T
+    /// -   Parameter value:
     ///     A gray value.
     /// ## ()
     @inlinable
@@ -53,9 +53,9 @@ extension PNG.VA
     ///
     ///     The ``v`` component will be set to `value`,
     ///     and the ``a`` component will be set to `alpha`.
-    /// - value : T
+    /// -   Parameter value:
     ///     A gray value.
-    /// - alpha : T
+    /// -   Parameter alpha:
     ///     An alpha value.
     /// ## ()
     @inlinable
@@ -92,10 +92,10 @@ extension PNG.VA
     ///     on ``v``, after scaling it to the range of `U`.
     ///     The returned component is then scaled back to the range of ``T``.
     ///     The rescaling operation also affects the ``a`` component.
-    /// - _ : U.Type
+    /// -   Parameter _:
     ///     The integer type to perform the premultiplications in. `U.bitWidth`
     ///     must be less than [`T`bitWidth`].
-    /// - -> : Self
+    /// -   Returns:
     ///     The premultiplied color.
     @inlinable
     public
@@ -138,10 +138,10 @@ extension PNG.VA
     ///     on ``v``, after scaling it to the range of `U`.
     ///     The returned component is then scaled back to the range of ``T``.
     ///     The rescaling operation also affects the ``a`` component.
-    /// - _ : U.Type
+    /// -   Parameter _:
     ///     The integer type to perform the straightening in. `U.bitWidth`
     ///     must be less than [`T`bitWidth`].
-    /// - -> : Self
+    /// -   Returns:
     ///     The straightened color.
     @inlinable
     public
@@ -193,24 +193,24 @@ extension PNG.VA:PNG.Color
     ///     This function will apply chroma keys if present. The unpacked components
     ///     are scaled to fill the range of ``T``, according to the color depth
     ///     computed from the color `format`.
-    /// - interleaved : [Swift.UInt8]
+    /// -   Parameter interleaved:
     ///     An image data buffer. It is expected to be obtained from the
     ///     ``Data.Rectangular/storage`` property of a ``Data/Rectangular``
     ///     image.
-    /// - format : Format
+    /// -   Parameter format:
     ///     The color format associated with the given data buffer.
     ///     It is expected to be obtained from the the
     ///     [`(Data.Rectangular).layout``(Layout).format`] property of a
     ///     ``Data/Rectangular`` image.
-    /// - deindexer : ([(r:Swift.UInt8, g:Swift.UInt8, b:Swift.UInt8, a:Swift.UInt8)]) -> (Swift.Int) -> Aggregate
+    /// -   Parameter deindexer:
     ///     A function which uses the palette entries in the color `format` to
     ///     generate a dereferencing function. This function is only invoked
     ///     if the color `format` is an indexed format. Its palette aggregates
     ///     will be interpreted as (*gray*, *alpha*) pairs.
     ///
     ///     See the [indexed color tutorial](https://github.com/tayloraswift/swift-png/tree/master/examples#using-indexed-images)
     ///     for more about the semantics of this function.
-    /// - -> : [Self]
+    /// -   Returns:
     ///     An array of RGBA pixels. The pixels
     ///     appear in the same order as they do in the image data buffer.
     @_specialize(where T == UInt8)
@@ -347,23 +347,23 @@ extension PNG.VA:PNG.Color
     ///
     ///     The components in each grayscale-alpha pixel are assumed to fill the entire
     ///     range of ``T``.
-    /// - pixels : [Self]
+    /// -   Parameter pixels:
     ///     An array of grayscale-alpha pixels.
-    /// - format : Format
+    /// -   Parameter format:
     ///     The color format to pack the given pixels as in the returned data buffer.
     ///
     ///     When the library uses an implementation of this function to construct
     ///     a ``Data/Rectangular`` image, this color format will be stored in
     ///     its [`(Data.Rectangular).layout``(Layout).format`] property.
-    /// - indexer : ([(r:Swift.UInt8, g:Swift.UInt8, b:Swift.UInt8, a:Swift.UInt8)]) -> (Aggregate) -> Swift.Int
+    /// -   Parameter indexer:
     ///     A function which uses the palette entries in the color `format` to
     ///     generate a referencing function. This function will only be invoked
     ///     if the color `format` is an indexed format. Its palette aggregates
     ///     will be interpreted as (*gray*, *alpha*) quadruplets.
     ///
     ///     See the [indexed color tutorial](https://github.com/tayloraswift/swift-png/tree/master/examples#using-indexed-images)
     ///     for more about the semantics of this function.
-    /// - -> : [Swift.UInt8]
+    /// -   Returns:
     ///     An image data buffer. The packed samples in this buffer appear
     ///     in the same order as the pixels in the `pixels` array.
     ///

Sources/PNG/Decoding/PNG.Context.swift

@@ -26,30 +26,30 @@ extension PNG.Context
     ///
     ///     It is expected that client applications will initialize a decoding
     ///     context upon encountering the first ``Chunk/IDAT`` chunk in the image.
-    /// - standard : Standard
+    /// -   Parameter standard:
     ///     The PNG standard of the image being decoded. This should be ``Standard/ios``
     ///     if the image began with a ``Chunk/CgBI`` chunk, and ``Standard/common``
     ///     otherwise.
-    /// - header : Header
+    /// -   Parameter header:
     ///     The header of the image being decoded. This is expected to have been
     ///     parsed from a previously-encountered ``Chunk/IHDR`` chunk.
-    /// - palette : Palette?
+    /// -   Parameter palette:
     ///     The palette of the image being decoded, if present. If not `nil`,
     ///     this is expected to have been parsed from a previously-encountered
     ///     ``Chunk/PLTE`` chunk.
-    /// - background : Background?
+    /// -   Parameter background:
     ///     The background descriptor of the image being decoded, if present.
     ///     If not `nil`, this is expected to have been parsed from a
     ///     previously-encountered ``Chunk/bKGD`` chunk.
-    /// - transparency : Transparency?
+    /// -   Parameter transparency:
     ///     The transparency descriptor of the image being decoded, if present.
     ///     If not `nil`, this is expected to have been parsed from a
     ///     previously-encountered ``Chunk/tRNS`` chunk.
-    /// - metadata : Metadata
+    /// -   Parameter metadata:
     ///     A metadata instance. It is expected to contain metadata from all
     ///     previously-encountered ancillary chunks, with the exception of
     ///     ``Chunk/bKGD`` and ``Chunk/tRNS``.
-    /// - uninitialized : Swift.Bool
+    /// -   Parameter uninitialized:
     ///     Specifies if the ``image`` ``Data.Rectangular/storage`` should
     ///     be initialized. If `false`, the storage buffer will be initialized
     ///     to all zeros. This can be safely set to `true` if there is no need
@@ -82,9 +82,9 @@ extension PNG.Context
     /// throws
     ///     Decompresses the contents of an ``Chunk/IDAT`` chunk, and updates
     ///     the image state with the newly-decompressed image data.
-    /// - data : [Swift.UInt8]
+    /// -   Parameter data:
     ///     The contents of the ``Chunk/IDAT`` chunk to process.
-    /// - overdraw : Swift.Bool
+    /// -   Parameter overdraw:
     ///     If `true`, pixels that are not yet available will be filled-in
     ///     with values from nearby available pixels. This option only has an
     ///     effect for ``Layout/interlaced`` images.
@@ -120,7 +120,7 @@ extension PNG.Context
     ///     Despite its name, this function can also accept an ``Chunk/IEND``
     ///     critical chunk, in which case this function will verify that the
     ///     compressed image data stream has been properly-terminated.
-    /// - chunk : (type:Chunk, data:[Swift.UInt8])
+    /// -   Parameter chunk:
     ///     The chunk to process. Its `type` must be one of ``Chunk/tIME``,
     ///     ``Chunk/iTXt``, ``Chunk/tEXt``, ``Chunk/zTXt``, or ``Chunk/IEND``,
     ///     or a private application data chunk type.

Sources/PNG/Decoding/PNG.DecodingError.swift

@@ -11,16 +11,16 @@ extension PNG
         /// case PNG.DecodingError.required(chunk:before:)
         ///     The decoder encountered a chunk of a type that requires a
         ///     previously encountered chunk of a particular type.
-        /// - chunk : Chunk
+        /// -   Parameter chunk:
         ///     The type of the preceeding chunk required by the encountered chunk.
-        /// - before : Chunk
+        /// -   Parameter before:
         ///     The type of the encountered chunk.
         /// ## ()
 
         /// case PNG.DecodingError.duplicate(chunk:)
         ///     The decoder encountered multiple instances of a chunk type that
         ///     can only appear once in a PNG file.
-        /// - chunk : Chunk
+        /// -   Parameter chunk:
         ///     The type of the duplicated chunk.
         /// ## ()
 
@@ -30,9 +30,9 @@ extension PNG
         ///
         ///     If both fields are set to ``Chunk/IDAT``, this indicates
         ///     a non-contiguous ``Chunk/IDAT`` sequence.
-        /// - chunk : Chunk
+        /// -   Parameter chunk:
         ///     The type of the encountered chunk.
-        /// - after : Chunk
+        /// -   Parameter after:
         ///     The type of the preceeding chunk that precludes the encountered chunk.
         /// ## ()
         case required(chunk:PNG.Chunk, before:PNG.Chunk)

Sources/PNG/Layout/PNG.Data.Rectangular.swift

@@ -126,14 +126,14 @@ extension PNG.Data.Rectangular
     ///     This interface can be used to switch image layouts without unpacking
     ///     to and repacking from a color target array. Rebinding to an
     ///     incompatible layout will result in a precondition failure.
-    /// - layout : Layout
+    /// -   Parameter layout:
     ///     The new image layout.
     ///
     ///     Both the original color ``Layout/format`` and the new
     ///     color ``Layout/format`` must be of the same enumeration case, though the fields
     ///     may differ. The exceptions are the indexed color formats, which require
     ///     the lengths of their `palette` payloads to match exactly.
-    /// - -> : Self
+    /// -   Returns:
     ///     An image with the given layout. This image will share backing ``storage``
     ///     with the original image until it is copied-on-write.
     public
@@ -329,9 +329,9 @@ extension PNG.Data.Rectangular
     ///
     ///     On appropriate platforms, the ``decompress(path:)`` function provides
     ///     a file system-aware interface to this function.
-    /// - stream : inout Source
+    /// -   Parameter stream:
     ///     A bytestream providing the contents of a PNG file.
-    /// - -> : Self
+    /// -   Returns:
     ///     The decoded image.
     /// # [See also](encoding-and-decoding)
     /// ## (0:encoding-and-decoding)
@@ -604,16 +604,16 @@ extension PNG.Data.Rectangular
     ///
     ///     On appropriate platforms, the ``compress(path:level:hint:)`` function
     ///     provides a file system-aware interface to this function.
-    /// - stream : inout Destination
+    /// -   Parameter stream:
     ///     A bytestream receiving the contents of a PNG file.
-    /// - level : Swift.Int
+    /// -   Parameter level:
     ///     The compression level to use. It should be in the range `0 ... 13`,
     ///     where `13` is the most aggressive setting. The default value is `9`.
     ///
     ///     Setting this parameter to a value less than `0` is the same as
     ///     setting it to `0`. Likewise, setting it to a value greater than `13`
     ///     is the same as setting it to `13`.
-    /// - hint : Swift.Int
+    /// -   Parameter hint:
     ///     A size hint for the emitted ``Chunk/IDAT`` chunks. It should be in
     ///     the range `1 ... 2147483647`. Reasonable settings range from around
     ///     1\ K to 64\ K. The default value is `32768` (2^15^).