diff --git a/Sources/PNG/ColorTargets/PNG.Data.Rectangular (ext).swift b/Sources/PNG/ColorTargets/PNG.Data.Rectangular (ext).swift index db715135..0d8faf0d 100644 --- a/Sources/PNG/ColorTargets/PNG.Data.Rectangular (ext).swift +++ b/Sources/PNG/ColorTargets/PNG.Data.Rectangular (ext).swift @@ -165,27 +165,23 @@ extension PNG.Data.Rectangular // custom-indexer APIs extension PNG.Data.Rectangular { - /// func PNG.Data.Rectangular.unpack(as:deindexer:) - /// where Color:Color - /// @ inlinable - /// Unpacks this image to a pixel array, using a custom deindexing - /// function. - /// - _ : Color.Type + /// Unpacks this image to a pixel array, using a custom deindexing function. + /// + /// - Parameter _: /// A color target type. This type provides the ``Color/unpack(_:of:deindexer:)`` /// implementation used to unpack the image data. - /// - deindexer : ([(r:Swift.UInt8, g:Swift.UInt8, b:Swift.UInt8, a:Swift.UInt8)]) -> (Swift.Int) -> Color.Aggregate + /// - Parameter deindexer: /// A function which uses the palette entries in the color ``Layout/format`` to /// generate a dereferencing function. This function is only expected to /// be invoked if [`layout``(Layout).format`] is an indexed format. /// /// 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. - /// - -> : [Color] + /// + /// - Returns: /// A pixel array. Its elements are arranged in row-major order. The /// first pixel in this array corresponds to the top-left corner of /// the image. Its length is equal to [`size`x`] multiplied by [`size`y`]. - /// # [See also](unpacking-pixels) - /// ## (1:unpacking-pixels) @inlinable public func unpack(as _:Color.Type, @@ -195,46 +191,41 @@ extension PNG.Data.Rectangular { Color.unpack(self.storage, of: self.layout.format, deindexer: deindexer) } - /// func PNG.Data.Rectangular.unpack(as:deindexer:) - /// where T:Swift.FixedWidthInteger & Swift.UnsignedInteger - /// @ inlinable - /// Unpacks this image to a scalar pixel array, using a custom deindexing - /// function. + /// Unpacks this image to a scalar pixel array, using a custom deindexing function. + /// + /// For an image with a grayscale-alpha color ``Layout/format``, + /// this function selects the *v* component from pixels of the form (*v*, *a*) /// - /// For an image with a grayscale-alpha color ``Layout/format``, - /// this function selects the *v* component from pixels of the form (*v*, *a*) + /// For an image with an RGB color ``Layout/format``, + /// this function selects the *r* component from pixels of the form (*r*, *g*, *b*). /// - /// For an image with an RGB color ``Layout/format``, - /// this function selects the *r* component from pixels of the form (*r*, *g*, *b*). + /// For an image with an RGBA color ``Layout/format``, this function selects the *r* component from + /// pixels of the form (*r*, *g*, *b*, *a*). /// - /// For an image with an RGBA color ``Layout/format``, this function selects the *r* component from - /// pixels of the form (*r*, *g*, *b*, *a*). + /// For an image with a BGR color ``Layout/format``, + /// this function selects the *r* component from pixels of the form (*b*, *g*, *r*). /// - /// For an image with a BGR color ``Layout/format``, - /// this function selects the *r* component from pixels of the form (*b*, *g*, *r*). + /// For an image with a BGRA color ``Layout/format``, + /// this function selects the *r* component from pixels of the form (*b*, *g*, *r*, *a*). /// - /// For an image with a BGRA color ``Layout/format``, - /// this function selects the *r* component from pixels of the form (*b*, *g*, *r*, *a*). + /// This function ignores chroma keys, as its scalar color target is not + /// capable of representing transparency. The unpacked components + /// are scaled to fill the range of `T`, according to the color depth + /// computed from the color ``Layout/format``. /// - /// This function ignores chroma keys, as its scalar color target is not - /// capable of representing transparency. The unpacked components - /// are scaled to fill the range of `T`, according to the color depth - /// computed from the color ``Layout/format``. - /// - _ : T.Type + /// - Parameter _: /// A scalar color target type. - /// - deindexer : ([(r:Swift.UInt8, g:Swift.UInt8, b:Swift.UInt8, a:Swift.UInt8)]) -> (Swift.Int) -> Swift.UInt8 + /// - Parameter deindexer: /// A function which uses the palette entries in the color ``Layout/format`` to /// generate a dereferencing function. This function will only /// be invoked if [`layout``(Layout).format`] is an indexed format. /// /// 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. - /// - -> : [T] + /// - Returns: /// A scalar pixel array. Its elements are arranged in row-major order. The /// first pixel in this array corresponds to the top-left corner of /// the image. Its length is equal to [`size`x`] multiplied by [`size`y`]. - /// # [See also](unpacking-pixels) - /// ## (3:unpacking-pixels) @inlinable public func unpack(as _:T.Type, @@ -244,11 +235,9 @@ extension PNG.Data.Rectangular { Self.unpack(self.storage, of: self.layout.format, as: T.self, deindexer: deindexer) } - /// init PNG.Data.Rectangular.init(packing:size:layout:metadata:indexer:) - /// where Color:Color - /// @ inlinable - /// Creates an image from a pixel array, using a custom indexing function. - /// - pixels : [Color] + /// Creates an image from a pixel array, using a custom indexing function. + /// + /// - Parameter pixels: /// A pixel array. Its elements are arranged in row-major order. The /// first pixel in this array corresponds to the top-left corner of /// the image. The `Color` type provides the ``Color/pack(_:as:indexer:)`` @@ -256,22 +245,20 @@ extension PNG.Data.Rectangular /// /// The length of this array must match `size.x * size.y`. Passing an /// array of the wrong length will result in a precondition failure. - /// - size : (x:Swift.Int, y:Swift.Int) + /// - Parameter size: /// The size of the image. Both dimensions must be greater than zero. /// Passing an invalid image size will result in a precondition failure. - /// - layout : Layout + /// - Parameter layout: /// An image layout. - /// - metadata : Metadata + /// - Parameter metadata: /// A metadata structure. The default value is an empty metadata structure. - /// - indexer : ([(r:Swift.UInt8, g:Swift.UInt8, b:Swift.UInt8, a:Swift.UInt8)]) -> (Color.Aggregate) -> Swift.Int + /// - Parameter indexer: /// A function which uses the palette entries in the color ``Layout/format`` to /// generate a referencing function. This function is only expected to /// be invoked if the image color ``Layout/format`` is an indexed format. /// - /// 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. - /// # [See also](packing-pixels) - /// ## (1:packing-pixels) + /// 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. @inlinable public init(packing pixels:[Color], @@ -286,48 +273,42 @@ extension PNG.Data.Rectangular self.init(size: size, layout: layout, metadata: metadata, storage: Color.pack(pixels, as: layout.format, indexer: indexer)) } - /// init PNG.Data.Rectangular.init(packing:size:layout:metadata:indexer:) - /// where T:Swift.FixedWidthInteger & Swift.UnsignedInteger - /// @ inlinable - /// Creates an image from a scalar pixel array, using a custom indexing - /// function. - /// - /// For an image with a grayscale-alpha color ``Layout/format``, - /// this function assigns the gray channel to the given scalars, and - /// sets the alpha channel to `T.max`. - /// - /// For an image with an RGB or BGR color ``Layout/format``, - /// this function assigns all channels to the given scalars, replicating - /// each scalar three times. - /// - /// For an image with an RGBA or BGRA color ``Layout/format``, this - /// function assigns all opaque channels to the given scalars, replicating - /// each scalar three times, and sets the alpha channel to `T.max`. - /// - /// The scalar values are assumed to fill the entire range of `T`. - /// - pixels : [T] + /// Creates an image from a scalar pixel array, using a custom indexing function. + /// + /// For an image with a grayscale-alpha color ``Layout/format``, + /// this function assigns the gray channel to the given scalars, and + /// sets the alpha channel to `T.max`. + /// + /// For an image with an RGB or BGR color ``Layout/format``, + /// this function assigns all channels to the given scalars, replicating + /// each scalar three times. + /// + /// For an image with an RGBA or BGRA color ``Layout/format``, this + /// function assigns all opaque channels to the given scalars, replicating + /// each scalar three times, and sets the alpha channel to `T.max`. + /// + /// The scalar values are assumed to fill the entire range of `T`. + /// - Parameter pixels: /// A scalar pixel array. Its elements are arranged in row-major order. The /// first pixel in this array corresponds to the top-left corner of /// the image. /// /// The length of this array must match `size.x * size.y`. Passing an /// array of the wrong length will result in a precondition failure. - /// - size : (x:Swift.Int, y:Swift.Int) + /// - Parameter size: /// The size of the image. Both dimensions must be greater than zero. /// Passing an invalid image size will result in a precondition failure. - /// - layout : Layout + /// - Parameter layout: /// An image layout. - /// - metadata : Metadata + /// - Parameter metadata: /// A metadata structure. The default value is an empty metadata structure. - /// - indexer : ([(r:Swift.UInt8, g:Swift.UInt8, b:Swift.UInt8, a:Swift.UInt8)]) -> (Swift.UInt8) -> Swift.Int + /// - Parameter indexer: /// A function which uses the palette entries in the color ``Layout/format`` to /// generate a referencing function. This function will only /// be invoked if the image color ``Layout/format`` is an indexed format. /// - /// 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. - /// # [See also](packing-pixels) - /// ## (3:packing-pixels) + /// 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. @inlinable public init(packing pixels:[T], @@ -345,30 +326,24 @@ extension PNG.Data.Rectangular } extension PNG.Data.Rectangular { - /// func PNG.Data.Rectangular.unpack(as:) - /// where Color:Color - /// @ inlinable - /// Unpacks this image to a pixel array. - /// - _ : Color.Type + /// Unpacks this image to a pixel array. + /// + /// - Parameter _: /// A color target type. This type provides the ``Color/unpack(_:of:)`` /// implementation used to unpack the image data. - /// - -> : [Color] + /// - Returns: /// A pixel array. Its elements are arranged in row-major order. The /// first pixel in this array corresponds to the top-left corner of /// the image. Its length is equal to [`size`x`] multiplied by [`size`y`]. - /// # [See also](unpacking-pixels) - /// ## (0:unpacking-pixels) @inlinable public func unpack(as _:Color.Type) -> [Color] where Color:PNG.Color { Color.unpack(self.storage, of: self.layout.format) } - /// init PNG.Data.Rectangular.init(packing:size:layout:metadata:) - /// where Color:Color - /// @ inlinable - /// Creates an image from a pixel array. - /// - pixels : [Color] + /// Creates an image from a pixel array. + /// + /// - Parameter pixels: /// A pixel array. Its elements are arranged in row-major order. The /// first pixel in this array corresponds to the top-left corner of /// the image. The `Color` type provides the ``Color/pack(_:as:)`` @@ -376,15 +351,13 @@ extension PNG.Data.Rectangular /// /// The length of this array must match `size.x * size.y`. Passing an /// array of the wrong length will result in a precondition failure. - /// - size : (x:Swift.Int, y:Swift.Int) + /// - Parameter size: /// The size of the image. Both dimensions must be greater than zero. /// Passing an invalid image size will result in a precondition failure. - /// - layout : Layout + /// - Parameter layout: /// An image layout. - /// - metadata : Metadata + /// - Parameter metadata: /// A metadata structure. The default value is an empty metadata structure. - /// # [See also](packing-pixels) - /// ## (0:packing-pixels) @inlinable public init(packing pixels:[Color], @@ -398,43 +371,39 @@ extension PNG.Data.Rectangular self.init(size: size, layout: layout, metadata: metadata, storage: Color.pack(pixels, as: layout.format)) } - /// func PNG.Data.Rectangular.unpack(as:) - /// where T:Swift.FixedWidthInteger & Swift.UnsignedInteger - /// @ inlinable - /// Unpacks this image to a scalar pixel array. + /// Unpacks this image to a scalar pixel array. + /// + /// For an image with a grayscale-alpha color ``Layout/format``, + /// this function selects the *v* component from pixels of the form (*v*, *a*) /// - /// For an image with a grayscale-alpha color ``Layout/format``, - /// this function selects the *v* component from pixels of the form (*v*, *a*) + /// For an image with an RGB color ``Layout/format``, + /// this function selects the *r* component from pixels of the form (*r*, *g*, *b*). /// - /// For an image with an RGB color ``Layout/format``, - /// this function selects the *r* component from pixels of the form (*r*, *g*, *b*). + /// For an image with an indexed color ``Layout/format``, + /// this function selects the *r* component from palette entries of the + /// form (*r*, *g*, *b*, *a*). The palette entry is chosen by taking the + /// i*th element in the palette, from pixels of the form (*i*). /// - /// For an image with an indexed color ``Layout/format``, - /// this function selects the *r* component from palette entries of the - /// form (*r*, *g*, *b*, *a*). The palette entry is chosen by taking the - /// *i*th element in the palette, from pixels of the form (*i*). + /// For an image with an RGBA color ``Layout/format``, this function + /// selects the *r* component from pixels of the form (*r*, *g*, *b*, *a*). /// - /// For an image with an RGBA color ``Layout/format``, this function - /// selects the *r* component from pixels of the form (*r*, *g*, *b*, *a*). + /// For an image with a BGR color ``Layout/format``, + /// this function selects the *r* component from pixels of the form (*b*, *g*, *r*). /// - /// For an image with a BGR color ``Layout/format``, - /// this function selects the *r* component from pixels of the form (*b*, *g*, *r*). + /// For an image with a BGRA color ``Layout/format``, + /// this function selects the *r* component from pixels of the form (*b*, *g*, *r*, *a*). /// - /// For an image with a BGRA color ``Layout/format``, - /// this function selects the *r* component from pixels of the form (*b*, *g*, *r*, *a*). + /// This function ignores chroma keys, as its scalar color target is not + /// capable of representing transparency. The unpacked components + /// are scaled to fill the range of `T`, according to the color depth + /// computed from the color ``Layout/format``. /// - /// This function ignores chroma keys, as its scalar color target is not - /// capable of representing transparency. The unpacked components - /// are scaled to fill the range of `T`, according to the color depth - /// computed from the color ``Layout/format``. - /// - _ : T.Type + /// - Parameter _: /// A scalar color target type. - /// - -> : [T] + /// - Returns: /// A scalar pixel array. Its elements are arranged in row-major order. The /// first pixel in this array corresponds to the top-left corner of /// the image. Its length is equal to [`size`x`] multiplied by [`size`y`]. - /// # [See also](unpacking-pixels) - /// ## (2:unpacking-pixels) @inlinable public func unpack(as _:T.Type) -> [T] where T:FixedWidthInteger & UnsignedInteger @@ -447,47 +416,42 @@ extension PNG.Data.Rectangular } } } - /// init PNG.Data.Rectangular.init(packing:size:layout:metadata:) - /// where T:Swift.FixedWidthInteger & Swift.UnsignedInteger - /// @ inlinable - /// Creates an image from a scalar pixel array. - /// - /// For an image with a grayscale-alpha color ``Layout/format``, - /// this function assigns the gray channel to the given scalars, and - /// sets the alpha channel to `T.max`. - /// - /// For an image with an indexed color ``Layout/format``, - /// this function expands the given scalars, each of the form (*v*), to - /// RGBA quadruplets (*v*, *v*, *v*, `T.max`), and assigns the index - /// channel to the index of a matching palette entry. If more than one - /// palette entry matches, the matching entry is chosen arbitrarily. - /// If no palette entries match, the first palette entry is chosen. - /// - /// For an image with an RGB or BGR color ``Layout/format``, - /// this function assigns all channels to the given scalars, replicating - /// each scalar three times. - /// - /// For an image with an RGBA or BGRA color ``Layout/format``, this - /// function assigns all opaque channels to the given scalars, replicating - /// each scalar three times, and sets the alpha channel to `T.max`. - /// - /// The scalar values are assumed to fill the entire range of `T`. - /// - pixels : [T] + /// Creates an image from a scalar pixel array. + /// + /// For an image with a grayscale-alpha color ``Layout/format``, + /// this function assigns the gray channel to the given scalars, and + /// sets the alpha channel to `T.max`. + /// + /// For an image with an indexed color ``Layout/format``, + /// this function expands the given scalars, each of the form (*v*), to + /// RGBA quadruplets (*v*, *v*, *v*, `T.max`), and assigns the index + /// channel to the index of a matching palette entry. If more than one + /// palette entry matches, the matching entry is chosen arbitrarily. + /// If no palette entries match, the first palette entry is chosen. + /// + /// For an image with an RGB or BGR color ``Layout/format``, + /// this function assigns all channels to the given scalars, replicating + /// each scalar three times. + /// + /// For an image with an RGBA or BGRA color ``Layout/format``, this + /// function assigns all opaque channels to the given scalars, replicating + /// each scalar three times, and sets the alpha channel to `T.max`. + /// + /// The scalar values are assumed to fill the entire range of `T`. + /// - Parameter pixels: /// A scalar pixel array. Its elements are arranged in row-major order. The /// first pixel in this array corresponds to the top-left corner of /// the image. /// /// The length of this array must match `size.x * size.y`. Passing an /// array of the wrong length will result in a precondition failure. - /// - size : (x:Swift.Int, y:Swift.Int) + /// - Parameter size: /// The size of the image. Both dimensions must be greater than zero. /// Passing an invalid image size will result in a precondition failure. - /// - layout : Layout + /// - Parameter layout: /// An image layout. - /// - metadata : Metadata + /// - Parameter metadata: /// A metadata structure. The default value is an empty metadata structure. - /// # [See also](packing-pixels) - /// ## (2:packing-pixels) @inlinable public init(packing pixels:[T], diff --git a/Sources/PNG/ColorTargets/PNG.RGBA.swift b/Sources/PNG/ColorTargets/PNG.RGBA.swift index b723ec6b..70e4f4c9 100644 --- a/Sources/PNG/ColorTargets/PNG.RGBA.swift +++ b/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 + /// - 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,16 +282,16 @@ 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 @@ -299,7 +299,7 @@ extension PNG.RGBA:PNG.Color /// /// 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,15 +435,15 @@ 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 @@ -451,7 +451,7 @@ extension PNG.RGBA:PNG.Color /// /// 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.) diff --git a/Sources/PNG/ColorTargets/PNG.VA.swift b/Sources/PNG/ColorTargets/PNG.VA.swift index 4606a91c..b7fa8eae 100644 --- a/Sources/PNG/ColorTargets/PNG.VA.swift +++ b/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,16 +193,16 @@ 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 @@ -210,7 +210,7 @@ extension PNG.VA:PNG.Color /// /// 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,15 +347,15 @@ 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 @@ -363,7 +363,7 @@ extension PNG.VA:PNG.Color /// /// 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. /// diff --git a/Sources/PNG/Decoding/PNG.Context.swift b/Sources/PNG/Decoding/PNG.Context.swift index 0f781c03..75a7dc94 100644 --- a/Sources/PNG/Decoding/PNG.Context.swift +++ b/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. diff --git a/Sources/PNG/Decoding/PNG.DecodingError.swift b/Sources/PNG/Decoding/PNG.DecodingError.swift index 4621b113..4214d8fa 100644 --- a/Sources/PNG/Decoding/PNG.DecodingError.swift +++ b/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) diff --git a/Sources/PNG/Layout/PNG.Data.Rectangular.swift b/Sources/PNG/Layout/PNG.Data.Rectangular.swift index e95f5301..7492d658 100644 --- a/Sources/PNG/Layout/PNG.Data.Rectangular.swift +++ b/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^). diff --git a/Sources/PNG/Layout/PNG.Layout.swift b/Sources/PNG/Layout/PNG.Layout.swift index e0b54ca1..ecbd6696 100644 --- a/Sources/PNG/Layout/PNG.Layout.swift +++ b/Sources/PNG/Layout/PNG.Layout.swift @@ -24,9 +24,9 @@ extension PNG /// This initializer will validate the fields of the given color /// `format`. Passing an invalid `format` will result in a /// precondition failure. - /// - format : Format + /// - Parameter format: /// A color format. - /// - interlaced : Swift.Bool + /// - Parameter interlaced: /// Specifies if the image uses interlacing. The default value is /// `false`. public diff --git a/Sources/PNG/Layout/PNG.swift b/Sources/PNG/Layout/PNG.swift index 7d7d8409..5fd94926 100644 --- a/Sources/PNG/Layout/PNG.swift +++ b/Sources/PNG/Layout/PNG.swift @@ -171,13 +171,13 @@ extension PNG /// A worked example of how to use this function to implement a custom /// color target can be found in the /// [custom color targets tutorial](https://github.com/tayloraswift/swift-png/tree/master/examples#custom-color-targets). - /// - buffer : [Swift.UInt8] + /// - Parameter buffer: /// An image data buffer. - /// - dereference : (Swift.Int) -> A + /// - Parameter dereference: /// A dereferencing function. - /// - kernel : (T) -> C + /// - Parameter kernel: /// A pixel kernel. - /// - -> : [C] + /// - Returns: /// An array of pixels constructed by the given `kernel` function. /// This array has the same number of elements as `buffer`. /// # [See also](convolution) @@ -227,13 +227,13 @@ extension PNG /// A worked example of how to use this function to implement a custom /// color target can be found in the /// [custom color targets tutorial](https://github.com/tayloraswift/swift-png/tree/master/examples#custom-color-targets). - /// - buffer : [Swift.UInt8] + /// - Parameter buffer: /// An image data buffer. - /// - dereference : (Swift.Int) -> (A, A) + /// - Parameter dereference: /// A dereferencing function. - /// - kernel : ((T, T)) -> C + /// - Parameter kernel: /// A pixel kernel. - /// - -> : [C] + /// - Returns: /// An array of pixels constructed by the given `kernel` function. /// This array has the same number of elements as `buffer`. /// # [See also](convolution) @@ -283,13 +283,13 @@ extension PNG /// A worked example of how to use this function to implement a custom /// color target can be found in the /// [custom color targets tutorial](https://github.com/tayloraswift/swift-png/tree/master/examples#custom-color-targets). - /// - buffer : [Swift.UInt8] + /// - Parameter buffer: /// An image data buffer. - /// - dereference : (Swift.Int) -> (A, A, A) + /// - Parameter dereference: /// A dereferencing function. - /// - kernel : ((T, T, T)) -> C + /// - Parameter kernel: /// A pixel kernel. - /// - -> : [C] + /// - Returns: /// An array of pixels constructed by the given `kernel` function. /// This array has the same number of elements as `buffer`. /// # [See also](convolution) @@ -339,13 +339,13 @@ extension PNG /// A worked example of how to use this function to implement a custom /// color target can be found in the /// [custom color targets tutorial](https://github.com/tayloraswift/swift-png/tree/master/examples#custom-color-targets). - /// - buffer : [Swift.UInt8] + /// - Parameter buffer: /// An image data buffer. - /// - dereference : (Swift.Int) -> (A, A, A, A) + /// - Parameter dereference: /// A dereferencing function. - /// - kernel : ((T, T, T, T)) -> C + /// - Parameter kernel: /// A pixel kernel. - /// - -> : [C] + /// - Returns: /// An array of pixels constructed by the given `kernel` function. /// This array has the same number of elements as `buffer`. /// # [See also](convolution) @@ -398,16 +398,16 @@ extension PNG /// A worked example of how to use this function to implement a custom /// color target can be found in the /// [custom color targets tutorial](https://github.com/tayloraswift/swift-png/tree/master/examples#custom-color-targets). - /// - buffer : [Swift.UInt8] + /// - Parameter buffer: /// An image data buffer. Its length must be divisible by the stride of `A`. - /// - _ : A.Type + /// - Parameter _: /// An atom type. - /// - depth : Swift.Int + /// - Parameter depth: /// A color depth used to interpret the intensity of each atom. /// This depth must be no greater than `A.bitWidth`. - /// - kernel : (T, A) -> C + /// - Parameter kernel: /// A pixel kernel. - /// - -> : [C] + /// - Returns: /// An array of pixels constructed by the given `kernel` function. /// This array has a length of `buffer.count` divided by the stride of `A`. /// # [See also](convolution) @@ -457,17 +457,17 @@ extension PNG /// A worked example of how to use this function to implement a custom /// color target can be found in the /// [custom color targets tutorial](https://github.com/tayloraswift/swift-png/tree/master/examples#custom-color-targets). - /// - buffer : [Swift.UInt8] + /// - Parameter buffer: /// An image data buffer. Its length must be divisible by twice the /// stride of `A`. - /// - _ : A.Type + /// - Parameter _: /// An atom type. - /// - depth : Swift.Int + /// - Parameter depth: /// A color depth used to interpret the intensity of each atom. /// This depth must be no greater than `A.bitWidth`. - /// - kernel : ((T, T)) -> C + /// - Parameter kernel: /// A pixel kernel. - /// - -> : [C] + /// - Returns: /// An array of pixels constructed by the given `kernel` function. /// This array has a length of `buffer.count` divided by the twice the /// stride of `A`. @@ -519,17 +519,17 @@ extension PNG /// A worked example of how to use this function to implement a custom /// color target can be found in the /// [custom color targets tutorial](https://github.com/tayloraswift/swift-png/tree/master/examples#custom-color-targets). - /// - buffer : [Swift.UInt8] + /// - Parameter buffer: /// An image data buffer. Its length must be divisible by three times the /// stride of `A`. - /// - _ : A.Type + /// - Parameter _: /// An atom type. - /// - depth : Swift.Int + /// - Parameter depth: /// A color depth used to interpret the intensity of each atom. /// This depth must be no greater than `A.bitWidth`. - /// - kernel : ((T, T, T), (A, A, A)) -> C + /// - Parameter kernel: /// A pixel kernel. - /// - -> : [C] + /// - Returns: /// An array of pixels constructed by the given `kernel` function. /// This array has a length of `buffer.count` divided by the three times /// the stride of `A`. @@ -580,17 +580,17 @@ extension PNG /// A worked example of how to use this function to implement a custom /// color target can be found in the /// [custom color targets tutorial](https://github.com/tayloraswift/swift-png/tree/master/examples#custom-color-targets). - /// - buffer : [Swift.UInt8] + /// - Parameter buffer: /// An image data buffer. Its length must be divisible by four times the /// stride of `A`. - /// - _ : A.Type + /// - Parameter _: /// An atom type. - /// - depth : Swift.Int + /// - Parameter depth: /// A color depth used to interpret the intensity of each atom. /// This depth must be no greater than `A.bitWidth`. - /// - kernel : ((T, T, T, T)) -> C + /// - Parameter kernel: /// A pixel kernel. - /// - -> : [C] + /// - Returns: /// An array of pixels constructed by the given `kernel` function. /// This array has a length of `buffer.count` divided by the four times /// the stride of `A`. @@ -743,15 +743,15 @@ extension PNG /// A worked example of how to use this function to implement a custom /// color target can be found in the /// [custom color targets tutorial](https://github.com/tayloraswift/swift-png/tree/master/examples#custom-color-targets). - /// - pixels : [C] + /// - Parameter pixels: /// A pixel array. - /// - reference : (A) -> Swift.Int + /// - Parameter reference: /// A referencing function. Its return value must be in the range `0 ... 255`. /// Depending on bit depth of the image it is being used for, there may /// be further restrictions on the range of the returned indices. - /// - kernel : (C) -> T + /// - Parameter kernel: /// A pixel kernel. - /// - -> : [Swift.UInt8] + /// - Returns: /// An image data buffer. /// This array has the same number of elements as `pixels`. /// # [See also](deconvolution) @@ -809,15 +809,15 @@ extension PNG /// A worked example of how to use this function to implement a custom /// color target can be found in the /// [custom color targets tutorial](https://github.com/tayloraswift/swift-png/tree/master/examples#custom-color-targets). - /// - pixels : [C] + /// - Parameter pixels: /// A pixel array. - /// - reference : ((A, A)) -> Swift.Int + /// - Parameter reference: /// A referencing function. Its return value must be in the range `0 ... 255`. /// Depending on bit depth of the image it is being used for, there may /// be further restrictions on the range of the returned indices. - /// - kernel : (C) -> (T, T) + /// - Parameter kernel: /// A pixel kernel. - /// - -> : [Swift.UInt8] + /// - Returns: /// An image data buffer. /// This array has the same number of elements as `pixels`. /// # [See also](deconvolution) @@ -875,15 +875,15 @@ extension PNG /// A worked example of how to use this function to implement a custom /// color target can be found in the /// [custom color targets tutorial](https://github.com/tayloraswift/swift-png/tree/master/examples#custom-color-targets). - /// - pixels : [C] + /// - Parameter pixels: /// A pixel array. - /// - reference : ((A, A, A)) -> Swift.Int + /// - Parameter reference: /// A referencing function. Its return value must be in the range `0 ... 255`. /// Depending on bit depth of the image it is being used for, there may /// be further restrictions on the range of the returned indices. - /// - kernel : (C) -> (T, T, T) + /// - Parameter kernel: /// A pixel kernel. - /// - -> : [Swift.UInt8] + /// - Returns: /// An image data buffer. /// This array has the same number of elements as `pixels`. /// # [See also](deconvolution) @@ -941,15 +941,15 @@ extension PNG /// A worked example of how to use this function to implement a custom /// color target can be found in the /// [custom color targets tutorial](https://github.com/tayloraswift/swift-png/tree/master/examples#custom-color-targets). - /// - pixels : [C] + /// - Parameter pixels: /// A pixel array. - /// - reference : ((A, A, A, A)) -> Swift.Int + /// - Parameter reference: /// A referencing function. Its return value must be in the range `0 ... 255`. /// Depending on bit depth of the image it is being used for, there may /// be further restrictions on the range of the returned indices. - /// - kernel : (C) -> (T, T, T, T) + /// - Parameter kernel: /// A pixel kernel. - /// - -> : [Swift.UInt8] + /// - Returns: /// An image data buffer. /// This array has the same number of elements as `pixels`. /// # [See also](deconvolution) @@ -1006,16 +1006,16 @@ extension PNG /// A worked example of how to use this function to implement a custom /// color target can be found in the /// [custom color targets tutorial](https://github.com/tayloraswift/swift-png/tree/master/examples#custom-color-targets). - /// - pixels : [C] + /// - Parameter pixels: /// A pixel array. - /// - _ : A.Type + /// - Parameter _: /// An atom type. - /// - depth : Swift.Int + /// - Parameter depth: /// A color depth specifying the range of the atom values. This depth /// can be no greater than `A.bitWidth`. - /// - kernel : (C) -> T + /// - Parameter kernel: /// A pixel kernel. - /// - -> : [Swift.UInt8] + /// - Returns: /// An image data buffer. /// This array has a length of `pixels.count`, multiplied by the stride /// of `A`. @@ -1073,16 +1073,16 @@ extension PNG /// A worked example of how to use this function to implement a custom /// color target can be found in the /// [custom color targets tutorial](https://github.com/tayloraswift/swift-png/tree/master/examples#custom-color-targets). - /// - pixels : [C] + /// - Parameter pixels: /// A pixel array. - /// - _ : A.Type + /// - Parameter _: /// An atom type. - /// - depth : Swift.Int + /// - Parameter depth: /// A color depth specifying the range of the atom values. This depth /// can be no greater than `A.bitWidth`. - /// - kernel : (C) -> (T, T) + /// - Parameter kernel: /// A pixel kernel. - /// - -> : [Swift.UInt8] + /// - Returns: /// An image data buffer. /// This array has a length of `pixels.count`, multiplied by twice the /// stride of `A`. @@ -1140,16 +1140,16 @@ extension PNG /// A worked example of how to use this function to implement a custom /// color target can be found in the /// [custom color targets tutorial](https://github.com/tayloraswift/swift-png/tree/master/examples#custom-color-targets). - /// - pixels : [C] + /// - Parameter pixels: /// A pixel array. - /// - _ : A.Type + /// - Parameter _: /// An atom type. - /// - depth : Swift.Int + /// - Parameter depth: /// A color depth specifying the range of the atom values. This depth /// can be no greater than `A.bitWidth`. - /// - kernel : (C) -> (T, T, T) + /// - Parameter kernel: /// A pixel kernel. - /// - -> : [Swift.UInt8] + /// - Returns: /// An image data buffer. /// This array has a length of `pixels.count`, multiplied by three times /// the stride of `A`. @@ -1207,16 +1207,16 @@ extension PNG /// A worked example of how to use this function to implement a custom /// color target can be found in the /// [custom color targets tutorial](https://github.com/tayloraswift/swift-png/tree/master/examples#custom-color-targets). - /// - pixels : [C] + /// - Parameter pixels: /// A pixel array. - /// - _ : A.Type + /// - Parameter _: /// An atom type. - /// - depth : Swift.Int + /// - Parameter depth: /// A color depth specifying the range of the atom values. This depth /// can be no greater than `A.bitWidth`. - /// - kernel : (C) -> (T, T, T, T) + /// - Parameter kernel: /// A pixel kernel. - /// - -> : [Swift.UInt8] + /// - Returns: /// An image data buffer. /// This array has a length of `pixels.count`, multiplied by four times /// the stride of `A`. diff --git a/Sources/PNG/Lexing/PNG.Chunk.swift b/Sources/PNG/Lexing/PNG.Chunk.swift index 5a4219c3..7ba540db 100644 --- a/Sources/PNG/Lexing/PNG.Chunk.swift +++ b/Sources/PNG/Lexing/PNG.Chunk.swift @@ -48,7 +48,7 @@ extension PNG /// For a failable version of this initializer, use ``init(validating:)``. /// For more details on type code semantics, consult the /// [PNG specification](http://www.libpng.org/pub/png/spec/1.2/PNG-Structure.html). - /// - name : Swift.UInt32 + /// - Parameter name: /// The chunk type code. Bit 13 must be set. If the type code is not /// a public PNG chunk type code, then bit 29 must be clear. /// # [See also](chunk-type-identifier-initializers) @@ -73,7 +73,7 @@ extension PNG /// is invalid. /// /// This initializer is a non-trapping version of ``init(name:)``. - /// - name : Swift.UInt32 + /// - Parameter name: /// The chunk type code. Bit 13 must be set. If the type code is not /// a public PNG chunk type code, then bit 29 must be clear. /// # [See also](chunk-type-identifier-initializers) diff --git a/Sources/PNG/Lexing/PNG.LexingError.swift b/Sources/PNG/Lexing/PNG.LexingError.swift index af1b0d37..ad86b08d 100644 --- a/Sources/PNG/Lexing/PNG.LexingError.swift +++ b/Sources/PNG/Lexing/PNG.LexingError.swift @@ -17,7 +17,7 @@ extension PNG /// sequence. /// /// The expected byte sequence is `[137, 80, 78, 71, 13, 10, 26, 10]`. - /// - _ : [Swift.UInt8] + /// - Parameter _: /// The invalid signature bytes. case invalidSignature([UInt8]) /// case PNG.LexingError.truncatedChunkHeader @@ -27,20 +27,20 @@ extension PNG /// case PNG.LexingError.truncatedChunkBody(expected:) /// The lexer encountered end-of-stream while reading a chunk body /// from a bytestream. - /// - expected : Swift.Int + /// - Parameter expected: /// The number of bytes the lexer expected to read. case truncatedChunkBody(expected:Int) /// case PNG.LexingError.invalidChunkTypeCode(_:) /// The lexer read a chunk with an invalid type identifier code. - /// - _ : Swift.UInt32 + /// - Parameter _: /// The invalid type identifier code. case invalidChunkTypeCode(UInt32) /// case PNG.LexingError.invalidChunkChecksum(declared:computed:) /// The chunk checksum computed by the lexer did not match the /// checksum declared in the chunk footer. - /// - declared : Swift.UInt32 + /// - Parameter declared: /// The checksum declared in the chunk footer. - /// - computed : Swift.UInt32 + /// - Parameter computed: /// The checksum computed by the lexer. case invalidChunkChecksum(declared:UInt32, computed:UInt32) } diff --git a/Sources/PNG/Lexing/_PNGBytestreamDestination.swift b/Sources/PNG/Lexing/_PNGBytestreamDestination.swift index ffeb1bd4..2b70e8a9 100644 --- a/Sources/PNG/Lexing/_PNGBytestreamDestination.swift +++ b/Sources/PNG/Lexing/_PNGBytestreamDestination.swift @@ -24,7 +24,7 @@ protocol _PNGBytestreamDestination /// as indicating a write failure. /// - bytes : [Swift.UInt8] /// The bytes to write. - /// - -> : Swift.Void? + /// - Returns: /// A ``Swift.Void`` tuple, or `nil` if the write attempt failed. This /// method should return `nil` even if any number of bytes less than /// `bytes.count` were successfully written. @@ -61,9 +61,9 @@ extension _PNGBytestreamDestination /// ``FormattingError`` if it fails to write to the bytestream. /// /// This function is the inverse of ``Source.chunk()``. - /// - type : PNG.Chunk + /// - Parameter type: /// The type identifier of the chunk to emit. - /// - data : [Swift.UInt8] + /// - Parameter data: /// The contents of the chunk to emit. It should not include a checksum /// footer, as this function computes and appends it automatically. /// diff --git a/Sources/PNG/Lexing/_PNGBytestreamSource.swift b/Sources/PNG/Lexing/_PNGBytestreamSource.swift index b1d7accf..e55dc1cb 100644 --- a/Sources/PNG/Lexing/_PNGBytestreamSource.swift +++ b/Sources/PNG/Lexing/_PNGBytestreamSource.swift @@ -24,7 +24,7 @@ protocol _PNGBytestreamSource /// as indicating end-of-stream. /// - count : Swift.Int /// The number of bytes to read. - /// - -> : [Swift.UInt8]? + /// - Returns: /// The `count` bytes read, or `nil` if the read attempt failed. This /// method should return `nil` even if any number of bytes less than `count` /// were successfully read. @@ -70,7 +70,7 @@ extension _PNGBytestreamSource /// catch these two error cases. /// /// This function is the inverse of ``Destination.format(type:data:)``. - /// - -> : (type:PNG.Chunk, data:[Swift.UInt8]) + /// - Returns: /// The type identifier, and contents of the lexed chunk. The chunk /// contents do not include the checksum footer. public mutating diff --git a/Sources/PNG/Parsing/PNG.Background.swift b/Sources/PNG/Parsing/PNG.Background.swift index 6cac6447..fc0a469f 100644 --- a/Sources/PNG/Parsing/PNG.Background.swift +++ b/Sources/PNG/Parsing/PNG.Background.swift @@ -29,7 +29,7 @@ extension PNG case palette(index:Int) /// case PNG.Background.Case.rgb(_:) /// A background descriptor for an RGB, BGR, RGBA, or BGRA image. - /// - _ : (r:Swift.UInt16, g:Swift.UInt16, b:Swift.UInt16) + /// - Parameter _: /// A background color. /// /// Note that the background components are unscaled samples. If @@ -38,7 +38,7 @@ extension PNG case rgb((r:UInt16, g:UInt16, b:UInt16)) /// case PNG.Background.Case.v(_:) /// A background descriptor for a grayscale or grayscale-alpha image. - /// - _ : Swift.UInt16 + /// - Parameter _: /// A background color. /// /// Note that the background value is an unscaled sample. If diff --git a/Sources/PNG/Parsing/PNG.Chromaticity.swift b/Sources/PNG/Parsing/PNG.Chromaticity.swift index 5038cca1..d4b66232 100644 --- a/Sources/PNG/Parsing/PNG.Chromaticity.swift +++ b/Sources/PNG/Parsing/PNG.Chromaticity.swift @@ -36,13 +36,13 @@ extension PNG /// init PNG.Chromaticity.init(w:r:g:b:) /// Creates a chromaticity descriptor with the given values. - /// - w : (x:Percentmille, y:Percentmille) + /// - Parameter w: /// The white point, expressed as a pair of fractions. - /// - r : (x:Percentmille, y:Percentmille) + /// - Parameter r: /// The red chromaticity, expressed as a pair of fractions. - /// - g : (x:Percentmille, y:Percentmille) + /// - Parameter g: /// The green chromaticity, expressed as a pair of fractions. - /// - b : (x:Percentmille, y:Percentmille) + /// - Parameter b: /// The blue chromaticity, expressed as a pair of fractions. public init( diff --git a/Sources/PNG/Parsing/PNG.ColorProfile.swift b/Sources/PNG/Parsing/PNG.ColorProfile.swift index d36eb049..f45c0f7b 100644 --- a/Sources/PNG/Parsing/PNG.ColorProfile.swift +++ b/Sources/PNG/Parsing/PNG.ColorProfile.swift @@ -24,14 +24,14 @@ extension PNG /// init PNG.ColorProfile.init(name:profile:) /// Creates a color profile. - /// - name : Swift.String + /// - Parameter name: /// The profile name. /// /// This string must contain only unicode scalars /// in the ranges `"\u{20}" ... "\u{7d}"` or `"\u{a1}" ... "\u{ff}"`. /// Leading, trailing, and consecutive spaces are not allowed. /// Passing an invalid string will result in a precondition failure. - /// - profile : [Swift.UInt8] + /// - Parameter profile: /// The uncompressed [ICC](http://www.color.org/index.xalter) color /// profile data. The data will be compressed when this color profile /// is ``serialized`` into an ``Chunk/iCCP`` chunk. diff --git a/Sources/PNG/Parsing/PNG.Gamma.swift b/Sources/PNG/Parsing/PNG.Gamma.swift index d87c121f..f99dc9c3 100644 --- a/Sources/PNG/Parsing/PNG.Gamma.swift +++ b/Sources/PNG/Parsing/PNG.Gamma.swift @@ -16,7 +16,7 @@ extension PNG let value:Percentmille /// init PNG.Gamma.init(value:) /// Creates a gamma descriptor with the given value. - /// - value : Percentmille + /// - Parameter value: /// A rational gamma value. public init(value:Percentmille) diff --git a/Sources/PNG/Parsing/PNG.Histogram.swift b/Sources/PNG/Parsing/PNG.Histogram.swift index d91ac0b3..33389d92 100644 --- a/Sources/PNG/Parsing/PNG.Histogram.swift +++ b/Sources/PNG/Parsing/PNG.Histogram.swift @@ -26,7 +26,7 @@ extension PNG.Histogram /// /// This initializer validates the background information against the /// given image palette. - /// - frequencies : [Swift.UInt16] + /// - Parameter frequencies: /// The frequency of each palette entry in the image. The *i*th frequency /// value corresponds to the *i*th palette entry. This array must have the /// the exact same number of elements as entries in the image palette. diff --git a/Sources/PNG/Parsing/PNG.ParsingError.swift b/Sources/PNG/Parsing/PNG.ParsingError.swift index 39e6ccf6..4230d353 100644 --- a/Sources/PNG/Parsing/PNG.ParsingError.swift +++ b/Sources/PNG/Parsing/PNG.ParsingError.swift @@ -26,13 +26,13 @@ extension PNG /// An ``Chunk/IHDR`` chunk had the wrong length. /// /// Header chunks should be exactly `13` bytes long. - /// - _ : Swift.Int + /// - Parameter _: /// The chunk length. /// ## (IHDR-parsing-errors) /// case PNG.ParsingError.invalidHeaderPixelFormatCode(_:) /// An ``Chunk/IHDR`` chunk had an invalid pixel format code. - /// - _ : (Swift.UInt8, Swift.UInt8) + /// - Parameter _: /// The invalid pixel format code. /// ## (IHDR-parsing-errors) @@ -43,9 +43,9 @@ extension PNG /// This error gets thrown when an iphone-optimized image /// (``Standard/ios``) has a pixel format that is not /// ``Format.Pixel/rgb8`` or ``Format.Pixel/rgba8``. - /// - _ : Format.Pixel + /// - Parameter _: /// The invalid pixel format. - /// - standard : Standard + /// - Parameter standard: /// The PNG standard. This error is only relevant for iphone-optimized /// images, so library-generated instances of this error case always have /// this field set to ``Standard/ios``. @@ -55,7 +55,7 @@ extension PNG /// An ``Chunk/IHDR`` chunk had an invalid compression method code. /// /// The compression method code should always be `0`. - /// - _ : Swift.UInt8 + /// - Parameter _: /// The invalid compression method code. /// ## (IHDR-parsing-errors) @@ -63,7 +63,7 @@ extension PNG /// An ``Chunk/IHDR`` chunk had an invalid filter code. /// /// The filter code should always be `0`. - /// - _ : Swift.UInt8 + /// - Parameter _: /// The invalid filter code. /// ## (IHDR-parsing-errors) @@ -71,7 +71,7 @@ extension PNG /// An ``Chunk/IHDR`` chunk had an invalid interlacing code. /// /// The interlacing code should be either `0` or `1`. - /// - _ : Swift.UInt8 + /// - Parameter _: /// The invalid interlacing code. /// ## (IHDR-parsing-errors) @@ -79,7 +79,7 @@ extension PNG /// An ``Chunk/IHDR`` chunk specified an invalid image size. /// /// Both size dimensions must be strictly positive. - /// - _ : (x:Swift.Int, y:Swift.Int) + /// - Parameter _: /// The invalid size. /// ## (IHDR-parsing-errors) case invalidHeaderChunkLength(Int) @@ -93,21 +93,21 @@ extension PNG /// case PNG.ParsingError.unexpectedPalette(pixel:) /// The parser encountered a ``Chunk/PLTE`` chunk in an image /// with a pixel format that forbids it. - /// - pixel : Format.Pixel + /// - Parameter pixel: /// The image pixel format. /// ## (PLTE-parsing-errors) /// case PNG.ParsingError.invalidPaletteChunkLength(_:) /// A ``Chunk/PLTE`` chunk had a length that is not divisible by `3`. - /// - _ : Swift.Int + /// - Parameter _: /// The chunk length. /// ## (PLTE-parsing-errors) /// case PNG.ParsingError.invalidPaletteCount(_:max:) /// A ``Chunk/PLTE`` chunk contained more entries than allowed. - /// - _ : Swift.Int + /// - Parameter _: /// The number of palette entries. - /// - max : Swift.Int + /// - Parameter max: /// The maximum allowed number of palette entries, according to the /// image bit depth. /// ## (PLTE-parsing-errors) @@ -118,32 +118,32 @@ extension PNG /// case PNG.ParsingError.unexpectedTransparency(pixel:) /// The parser encountered a ``Chunk/tRNS`` chunk in an image /// with a pixel format that forbids it. - /// - pixel : Format.Pixel + /// - Parameter pixel: /// The image pixel format. /// ## (tRNS-parsing-errors) /// case PNG.ParsingError.invalidTransparencyChunkLength(_:expected:) /// A ``Chunk/tRNS`` chunk had the wrong length. - /// - _ : Swift.Int + /// - Parameter _: /// The chunk length. - /// - expected : Swift.Int + /// - Parameter expected: /// The expected chunk length. /// ## (tRNS-parsing-errors) /// case PNG.ParsingError.invalidTransparencySample(_:max:) /// A ``Chunk/tRNS`` chunk contained an invalid chroma key sample. - /// - _ : Swift.UInt16 + /// - Parameter _: /// The value of the invalid chroma key sample. - /// - max : Swift.UInt16 + /// - Parameter max: /// The maximum allowed value for a chroma key sample, according to the /// image color depth. /// ## (tRNS-parsing-errors) /// case PNG.ParsingError.invalidTransparencyCount(_:max:) /// A ``Chunk/tRNS`` chunk contained too many alpha samples. - /// - _ : Swift.Int + /// - Parameter _: /// The number of alpha samples present. - /// - max : Swift.Int + /// - Parameter max: /// The maximum allowed number of alpha samples, which is equal to /// the number of entries in the image palette. /// ## (tRNS-parsing-errors) @@ -154,26 +154,26 @@ extension PNG /// case PNG.ParsingError.invalidBackgroundChunkLength(_:expected:) /// A ``Chunk/bKGD`` chunk had the wrong length. - /// - _ : Swift.Int + /// - Parameter _: /// The chunk length. - /// - expected : Swift.Int + /// - Parameter expected: /// The expected chunk length. /// ## (bKGD-parsing-errors) /// case PNG.ParsingError.invalidBackgroundSample(_:max:) /// A ``Chunk/bKGD`` chunk contained an invalid background sample. - /// - _ : Swift.UInt16 + /// - Parameter _: /// The value of the invalid background sample. - /// - max : Swift.UInt16 + /// - Parameter max: /// The maximum allowed value for a background sample, according to the /// image color depth. /// ## (bKGD-parsing-errors) /// case PNG.ParsingError.invalidBackgroundIndex(_:max:) /// A ``Chunk/bKGD`` chunk specified an out-of-range palette index. - /// - _ : Swift.Int + /// - Parameter _: /// The invalid index. - /// - max : Swift.Int + /// - Parameter max: /// The maximum allowed index value, which is equal to one less than /// the number of entries in the image palette. /// ## (bKGD-parsing-errors) @@ -183,9 +183,9 @@ extension PNG /// case PNG.ParsingError.invalidHistogramChunkLength(_:expected:) /// A ``Chunk/hIST`` chunk had the wrong length. - /// - _ : Swift.Int + /// - Parameter _: /// The chunk length. - /// - expected : Swift.Int + /// - Parameter expected: /// The expected chunk length. /// ## (hIST-parsing-errors) case invalidHistogramChunkLength(Int, expected:Int) @@ -194,7 +194,7 @@ extension PNG /// A ``Chunk/gAMA`` chunk had the wrong length. /// /// Gamma chunks should be exactly `4` bytes long. - /// - _ : Swift.Int + /// - Parameter _: /// The chunk length. /// ## (gAMA-parsing-errors) case invalidGammaChunkLength(Int) @@ -203,7 +203,7 @@ extension PNG /// A ``Chunk/cHRM`` chunk had the wrong length. /// /// Chromaticity chunks should be exactly `32` bytes long. - /// - _ : Swift.Int + /// - Parameter _: /// The chunk length. /// ## (cHRM-parsing-errors) case invalidChromaticityChunkLength(Int) @@ -212,7 +212,7 @@ extension PNG /// An ``Chunk/sRGB`` chunk had the wrong length. /// /// Color rendering chunks should be exactly `1` byte long. - /// - _ : Swift.Int + /// - Parameter _: /// The chunk length. /// ## (sRGB-parsing-errors) @@ -220,7 +220,7 @@ extension PNG /// An ``Chunk/sRGB`` chunk had an invalid color rendering code. /// /// The color rendering code should be one of `0`, `1`, `2`, or `3`. - /// - _ : Swift.UInt8 + /// - Parameter _: /// The invalid color rendering code. /// ## (sRGB-parsing-errors) case invalidColorRenderingChunkLength(Int) @@ -228,17 +228,17 @@ extension PNG /// case PNG.ParsingError.invalidSignificantBitsChunkLength(_:expected:) /// An ``Chunk/sBIT`` chunk had the wrong length. - /// - _ : Swift.Int + /// - Parameter _: /// The chunk length. - /// - expected : Swift.Int + /// - Parameter expected: /// The expected chunk length. /// ## (sBIT-parsing-errors) /// case PNG.ParsingError.invalidSignificantBitsPrecision(_:max:) /// An ``Chunk/sBIT`` chunk specified an invalid precision value. - /// - _ : Swift.Int + /// - Parameter _: /// The invalid precision value. - /// - max : Swift.Int + /// - Parameter max: /// The maximum allowed precision value, which is equal to the image /// color depth. /// ## (sBIT-parsing-errors) @@ -247,15 +247,15 @@ extension PNG /// case PNG.ParsingError.invalidColorProfileChunkLength(_:min:) /// An ``Chunk/iCCP`` chunk had an invalid length. - /// - _ : Swift.Int + /// - Parameter _: /// The chunk length. - /// - min : Swift.Int + /// - Parameter min: /// The minimum expected chunk length. /// ## (iCCP-parsing-errors) /// case PNG.ParsingError.invalidColorProfileName(_:) /// An ``Chunk/iCCP`` chunk had an invalid profile name. - /// - _ : Swift.String? + /// - Parameter _: /// The invalid profile name, or `nil` if the parser could not find /// the null-terminator of the profile name string. /// ## (iCCP-parsing-errors) @@ -264,7 +264,7 @@ extension PNG /// An ``Chunk/iCCP`` chunk had an invalid compression method code. /// /// The compression method code should always be `0`. - /// - _ : Swift.UInt8 + /// - Parameter _: /// The invalid compression method code. /// ## (iCCP-parsing-errors) @@ -281,7 +281,7 @@ extension PNG /// A ``Chunk/pHYs`` chunk had the wrong length. /// /// Physical dimensions chunks should be exactly `9` bytes long. - /// - _ : Swift.Int + /// - Parameter _: /// The chunk length. /// ## (pHYs-parsing-errors) @@ -289,7 +289,7 @@ extension PNG /// A ``Chunk/pHYs`` chunk had an invalid density unit code. /// /// The density code should be either `0` or `1`. - /// - _ : Swift.UInt8 + /// - Parameter _: /// The invalid density unit code. /// ## (pHYs-parsing-errors) case invalidPhysicalDimensionsChunkLength(Int) @@ -297,15 +297,15 @@ extension PNG /// case PNG.ParsingError.invalidSuggestedPaletteChunkLength(_:min:) /// An ``Chunk/sPLT`` chunk had an invalid length. - /// - _ : Swift.Int + /// - Parameter _: /// The chunk length. - /// - min : Swift.Int + /// - Parameter min: /// The minimum expected chunk length. /// ## (sPLT-parsing-errors) /// case PNG.ParsingError.invalidSuggestedPaletteName(_:) /// An ``Chunk/sPLT`` chunk had an invalid palette name. - /// - _ : Swift.String? + /// - Parameter _: /// The invalid palette name, or `nil` if the parser could not find /// the null-terminator of the palette name string. /// ## (sPLT-parsing-errors) @@ -313,9 +313,9 @@ extension PNG /// case PNG.ParsingError.invalidSuggestedPaletteDataLength(_:stride:) /// The length of the palette data in an ``Chunk/sPLT`` chunk was /// not divisible by its expected stride. - /// - _ : Swift.Int + /// - Parameter _: /// The length of the palette data. - /// - stride : Swift.Int + /// - Parameter stride: /// The expected stride of the palette entries. /// ## (sPLT-parsing-errors) @@ -323,7 +323,7 @@ extension PNG /// An ``Chunk/sPLT`` chunk had an invalid depth code. /// /// The depth code should be either `8` or `16`. - /// - _ : Swift.UInt8 + /// - Parameter _: /// The invalid depth code. /// ## (sPLT-parsing-errors) @@ -341,23 +341,23 @@ extension PNG /// A ``Chunk/tIME`` chunk had the wrong length. /// /// Time modified chunks should be exactly `7` bytes long. - /// - _ : Swift.Int + /// - Parameter _: /// The chunk length. /// ## (tIME-parsing-errors) /// case PNG.ParsingError.invalidTimeModifiedTime(year:month:day:hour:minute:second:) /// A ``Chunk/tIME`` chunk specified an invalid timestamp. - /// - year : Swift.Int + /// - Parameter year: /// The specified year. - /// - month : Swift.Int + /// - Parameter month: /// The specified month. - /// - day : Swift.Int + /// - Parameter day: /// The specified day. - /// - hour : Swift.Int + /// - Parameter hour: /// The specified hour. - /// - minute : Swift.Int + /// - Parameter minute: /// The specified minute. - /// - second : Swift.Int + /// - Parameter second: /// The specified second. /// ## (tIME-parsing-errors) case invalidTimeModifiedChunkLength(Int) @@ -366,7 +366,7 @@ extension PNG /// case PNG.ParsingError.invalidTextEnglishKeyword(_:) /// A ``Chunk/tEXt``, ``Chunk/zTXt``, or ``Chunk/iTXt`` chunk /// had an invalid english keyword. - /// - _ : Swift.String? + /// - Parameter _: /// The invalid english keyword, or `nil` if the parser could not find /// the null-terminator of the keyword string. /// ## (text-chunk-parsing-errors) @@ -374,9 +374,9 @@ extension PNG /// case PNG.ParsingError.invalidTextChunkLength(_:min:) /// A ``Chunk/tEXt``, ``Chunk/zTXt``, or ``Chunk/iTXt`` chunk /// had an invalid length. - /// - _ : Swift.Int + /// - Parameter _: /// The chunk length. - /// - min : Swift.Int + /// - Parameter min: /// The minimum expected chunk length. /// ## (text-chunk-parsing-errors) @@ -384,7 +384,7 @@ extension PNG /// An ``Chunk/iTXt`` chunk had an invalid compression code. /// /// The compression code should be either `0` or `1`. - /// - _ : Swift.UInt8 + /// - Parameter _: /// The invalid compression code. /// ## (text-chunk-parsing-errors) @@ -393,13 +393,13 @@ extension PNG /// compression method code. /// /// The compression method code should always be `0`. - /// - _ : Swift.UInt8 + /// - Parameter _: /// The invalid compression method code. /// ## (text-chunk-parsing-errors) /// case PNG.ParsingError.invalidTextLanguageTag(_:) /// An ``Chunk/iTXt`` chunk had an invalid language tag. - /// - _ : Swift.String? + /// - Parameter _: /// The invalid language tag component, or `nil` if the parser could /// not find the null-terminator of the language tag string. /// The language tag component is not the entire language tag string. diff --git a/Sources/PNG/Parsing/PNG.Percentmille.swift b/Sources/PNG/Parsing/PNG.Percentmille.swift index ea8db326..1fc8edb1 100644 --- a/Sources/PNG/Parsing/PNG.Percentmille.swift +++ b/Sources/PNG/Parsing/PNG.Percentmille.swift @@ -28,7 +28,7 @@ extension PNG /// /// The numerical value of this percentmille value will be the given /// numerator divided by `100000`. - /// - points : T + /// - Parameter points: /// The numerator. public init(_ points:T) where T:BinaryInteger @@ -44,7 +44,7 @@ extension PNG /// The provided integer literal is *not* the numerical value of the /// created percentmille value. It will be interpreted as the numerator /// of a rational value. - /// - integerLiteral : Swift.Int + /// - Parameter integerLiteral: /// The integer literal. public init(integerLiteral:Int) @@ -59,7 +59,7 @@ extension PNG /// The first value to add. /// - rhs : Self /// The second value to add. - /// - -> : Self + /// - Returns: /// The sum of the two given percentmille values. public static func + (lhs:Self, rhs:Self) -> Self @@ -87,7 +87,7 @@ extension PNG /// A percentmille value. /// - rhs : Self /// The value to subtract from `lhs`. - /// - -> : Self + /// - Returns: /// The difference of the two given percentmille values. public static func - (lhs:Self, rhs:Self) -> Self diff --git a/Sources/PNG/Parsing/PNG.PhysicalDimensions.swift b/Sources/PNG/Parsing/PNG.PhysicalDimensions.swift index 2e4a9919..510f1bb2 100644 --- a/Sources/PNG/Parsing/PNG.PhysicalDimensions.swift +++ b/Sources/PNG/Parsing/PNG.PhysicalDimensions.swift @@ -34,7 +34,7 @@ extension PNG /// init PNG.PhysicalDimensions.init(density:) /// Creates a physical dimensions descriptor. - /// - density : (x:Swift.Int, y:Swift.Int, unit:Unit?) + /// - Parameter density: /// The number of pixels in each dimension per the given `unit` of /// measurement. /// diff --git a/Sources/PNG/Parsing/PNG.SignificantBits.swift b/Sources/PNG/Parsing/PNG.SignificantBits.swift index e366f144..290d1f45 100644 --- a/Sources/PNG/Parsing/PNG.SignificantBits.swift +++ b/Sources/PNG/Parsing/PNG.SignificantBits.swift @@ -17,7 +17,7 @@ extension PNG { /// case PNG.SignificantBits.Case.v(_:) /// A color precision descriptor for a grayscale image. - /// - _ : Swift.Int + /// - Parameter _: /// The number of significant bits in each grayscale sample. /// /// This value must be greater than zero, and can be no greater @@ -26,7 +26,7 @@ extension PNG case v(Int) /// case PNG.SignificantBits.Case.va(_:) /// A color precision descriptor for a grayscale-alpha image. - /// - _ : (v:Swift.Int, a:Swift.Int) + /// - Parameter _: /// The number of significant bits in each grayscale and alpha /// sample, respectively. /// @@ -36,7 +36,7 @@ extension PNG case va((v:Int, a:Int)) /// case PNG.SignificantBits.Case.rgb(_:) /// A color precision descriptor for an RGB, BGR, or indexed image. - /// - _ : (r:Swift.Int, g:Swift.Int, b:Swift.Int) + /// - Parameter _: /// The number of significant bits in each red, green, and blue /// sample, respectively. If the image uses an indexed color format, /// the precision values refer to the precision of the palette @@ -57,7 +57,7 @@ extension PNG case rgb((r:Int, g:Int, b:Int)) /// case PNG.SignificantBits.Case.rgba(_:) /// A color precision descriptor for an RGBA or BGRA image. - /// - _ : (r:Swift.Int, g:Swift.Int, b:Swift.Int, a:Swift.Int) + /// - Parameter _: /// The number of significant bits in each red, green, blue, and alpha /// sample, respectively. /// diff --git a/Sources/PNG/Parsing/PNG.SuggestedPalette.swift b/Sources/PNG/Parsing/PNG.SuggestedPalette.swift index f310b2af..02ccc9c2 100644 --- a/Sources/PNG/Parsing/PNG.SuggestedPalette.swift +++ b/Sources/PNG/Parsing/PNG.SuggestedPalette.swift @@ -19,13 +19,13 @@ extension PNG { /// case PNG.SuggestedPalette.Entries.rgba8(_:) /// A suggested palette with an 8-bit color depth. - /// - _ : [(color:(r:Swift.UInt8, g:Swift.UInt8, b:Swift.UInt8, a:Swift.UInt8), frequency:Swift.UInt16)] + /// - Parameter _: /// An array of 8-bit palette colors and frequencies. /// ## () case rgba8( [(color:(r:UInt8, g:UInt8, b:UInt8, a:UInt8), frequency:UInt16)]) /// case PNG.SuggestedPalette.Entries.rgba16(_:) /// A suggested palette with a 16-bit color depth. - /// - _ : [(color:(r:Swift.UInt16, g:Swift.UInt16, b:Swift.UInt16, a:Swift.UInt16), frequency:Swift.UInt16)] + /// - Parameter _: /// An array of 16-bit palette colors and frequencies. /// ## () case rgba16([(color:(r:UInt16, g:UInt16, b:UInt16, a:UInt16), frequency:UInt16)]) @@ -41,14 +41,14 @@ extension PNG /// init PNG.SuggestedPalette.init(name:entries:) /// Creates a suggested palette. - /// - name : Swift.String + /// - Parameter name: /// The palette name. /// /// This string must contain only unicode scalars /// in the ranges `"\u{20}" ... "\u{7d}"` or `"\u{a1}" ... "\u{ff}"`. /// Leading, trailing, and consecutive spaces are not allowed. /// Passing an invalid string will result in a precondition failure. - /// - entries : Entries + /// - Parameter entries: /// A variant array of palette colors and frequencies. public init(name:String, entries:Entries) diff --git a/Sources/PNG/Parsing/PNG.Text.swift b/Sources/PNG/Parsing/PNG.Text.swift index f0c6de89..c3b6b518 100644 --- a/Sources/PNG/Parsing/PNG.Text.swift +++ b/Sources/PNG/Parsing/PNG.Text.swift @@ -43,10 +43,10 @@ extension PNG /// init PNG.Text.init(compressed:keyword:language:content:) /// Creates a text comment. - /// - compressed : Swift.Bool + /// - Parameter compressed: /// Indicates if the text is to be stored in compressed or /// uncompressed form within a PNG file. - /// - keyword : (english:Swift.String, localized:Swift.String) + /// - Parameter keyword: /// A keyword tag, in english, and possibly a non-english language. /// /// The english keyword must contain only unicode scalars @@ -59,7 +59,7 @@ extension PNG /// /// If the text is in english, the `localized` keyword should be /// set to the empty string `""`. - /// - language : [Swift.String] + /// - Parameter language: /// An array representing an [rfc-1766](https://www.ietf.org/rfc/rfc1766.txt) /// language tag, where each element is a language subtag. /// @@ -68,7 +68,7 @@ extension PNG /// will result in a precondition failure. /// /// If this array is empty, then the language is unspecified. - /// - content : Swift.String + /// - Parameter content: /// The text content. There are no restrictions on it. It is allowed /// (but not recommended) to contain null characters. public diff --git a/Sources/PNG/Parsing/PNG.TimeModified.swift b/Sources/PNG/Parsing/PNG.TimeModified.swift index 398b838e..209373c2 100644 --- a/Sources/PNG/Parsing/PNG.TimeModified.swift +++ b/Sources/PNG/Parsing/PNG.TimeModified.swift @@ -45,23 +45,23 @@ extension PNG /// The time is time-zone agnostic, and so all time parameters are /// assumed to be in universal time (UTC). Passing out-of-range /// time parameters will result in a precondition failure. - /// - year : Swift.Int + /// - Parameter year: /// The complete [gregorian](https://en.wikipedia.org/wiki/Gregorian_calendar) /// year. It must be in the range `0 ..< 1 << 16`. It can be /// reasonably expected to have four decimal digits. - /// - month : Swift.Int + /// - Parameter month: /// The calendar month, expressed as a 1-indexed integer. It must /// be in the range `1 ... 12`. - /// - day : Swift.Int + /// - Parameter day: /// The calendar day, expressed as a 1-indexed integer. /// It must be in the range `1 ... 31`. - /// - hour : Swift.Int + /// - Parameter hour: /// The hour, in 24-hour time, expressed as a 0-indexed integer. /// It must be in the range `0 ... 23`. - /// - minute : Swift.Int + /// - Parameter minute: /// The minute, expressed as a 0-indexed integer. /// It must be in the range `0 ... 59`. - /// - second : Swift.Int + /// - Parameter second: /// The second, expressed as a 0-indexed integer. /// It must be in the range `0 ... 60`, where the value `60` is /// used to represent leap seconds. diff --git a/Sources/PNG/System.swift b/Sources/PNG/System.swift index e59b880a..4eb4d325 100644 --- a/Sources/PNG/System.swift +++ b/Sources/PNG/System.swift @@ -76,7 +76,7 @@ extension System.File.Source /// opened, otherwise this method will return `nil`. If `body` has a /// return value and the specified file could be opened, this method /// returns the return value of the closure. - /// - -> : R? + /// - Returns: /// The return value of the closure argument, or `nil` if the specified /// file could not be opened. public static @@ -106,7 +106,7 @@ extension System.File.Source /// specified could be read. This method advances the file pointer. /// - capacity : Swift.Int /// The number of bytes to read. - /// - -> : [Swift.UInt8]? + /// - Returns: /// An array containing the read data, or `nil` if the specified /// number of bytes could not be read. public @@ -196,7 +196,7 @@ extension System.File.Destination /// be successfully opened, otherwise this method will return `nil`. /// If `body` has a return value and the specified file could be opened, /// this method returns the return value of the closure. - /// - -> : R? + /// - Returns: /// The return value of the closure argument, or `nil` if the specified /// file could not be opened. public static @@ -226,7 +226,7 @@ extension System.File.Destination /// be written. This method advances the file pointer. /// - buffer : [Swift.UInt8] /// The data to write. - /// - -> : Swift.Void? + /// - Returns: /// A ``Swift.Void`` tuple if the entire array argument could be written, /// or `nil` otherwise. public @@ -265,9 +265,9 @@ extension PNG.Data.Rectangular /// This interface is only available on MacOS and Linux. The /// ``decompress(stream:)`` function provides a platform-independent /// decoding interface. - /// - path : Swift.String + /// - Parameter path: /// A path to a PNG file. - /// - -> : Self? + /// - Returns: /// The decoded image, or `nil` if the file at the given `path` could /// not be opened. /// # [See also](encoding-and-decoding) @@ -297,16 +297,16 @@ extension PNG.Data.Rectangular /// This interface is only available on MacOS and Linux. The /// ``compress(stream:level:hint:)`` function provides a platform-independent /// encoding interface. - /// - path : Swift.String + /// - Parameter path: /// A path to save the PNG file at. - /// - 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^). @@ -314,7 +314,7 @@ extension PNG.Data.Rectangular /// Setting this parameter to a value less than `1` is the same as setting /// it to `1`. Likewise, setting it to a value greater than `2147483647` /// (2^31^\ –\ 1) is the same as setting it to `2147483647`. - /// - -> : Swift.Void? + /// - Returns: /// A ``Swift.Void`` tuple if the destination file could be opened /// successfully, or `nil` otherwise. /// # [See also](encoding-and-decoding)