Skip to content

Commit

Permalink
Merge pull request #25 from tayloraswift/port-docs
Browse files Browse the repository at this point in the history 
Port docs
  • Loading branch information
@tayloraswift
tayloraswift authored Nov 17, 2024
2 parents c5243c1 + a7abb16 commit 2582ae2
Show file tree
Hide file tree
Showing 15 changed files with 2,283 additions and 2,541 deletions.
48 changes: 48 additions & 0 deletions .github/workflows/Documentation.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
name: documentation

on:
push:
branches: [ master ]
pull_request:
branches: [ master ]

jobs:
linux:
runs-on: ubuntu-24.04
name: Ubuntu 24.04

steps:
- name: Install Swift
uses: tayloraswift/swift-install-action@master
with:
swift-prefix: "swift-6.0.2-release/ubuntu2404/swift-6.0.2-RELEASE"
swift-id: "swift-6.0.2-RELEASE-ubuntu24.04"

- name: Install Unidoc
uses: tayloraswift/swift-unidoc-action@master

- name: Checkout repository
uses: actions/checkout@v3

- name: Validate documentation
run: |
unidoc compile \
--swift-toolchain $SWIFT_INSTALLATION \
--ci fail-on-errors \
--project-path .
macos:
runs-on: macos-15
name: macOS
steps:
- name: Install Unidoc
uses: tayloraswift/swift-unidoc-action@master

- name: Checkout repository
uses: actions/checkout@v3

- name: Validate documentation
run: |
unidoc compile \
--ci fail-on-errors \
--project-path .
142 changes: 52 additions & 90 deletions Sources/JPEG/common.swift
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,67 +2,51 @@
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at https://mozilla.org/MPL/2.0/. */

/// enum General
/// A namespace for general functionality.
/// # [Range types](general-range-types)
/// # [Integer storage](general-storage-types)
/// # [See also](top-level-namespaces)
/// ## (1:top-level-namespaces)
/// A namespace for general functionality.
public
enum General
{
}

extension General
{
/// struct General.Storage<I>
/// where I:Swift.FixedWidthInteger & Swift.BinaryInteger
/// @propertyWrapper
/// A property wrapper providing an immutable [`Swift.Int`] interface backed
/// by a different integer type.
/// # [See also](general-storage-types)
/// ## (general-storage-types)
/// A property wrapper providing an immutable ``Int`` interface backed
/// by a different integer type.
@propertyWrapper
public
struct Storage<I> where I:FixedWidthInteger & BinaryInteger
{
private
var storage:I
/// init General.Storage.init(wrappedValue:)
/// Creates an instance of this property wrapper, with the given value
/// truncated to the width of the storage type [`I`].
/// - wrappedValue : Swift.Int
/// Creates an instance of this property wrapper, with the given value
/// truncated to the width of the storage type `I`.
///
/// - Parameter wrappedValue:
/// The value to wrap.
public
init(wrappedValue:Int)
{
self.storage = .init(truncatingIfNeeded: wrappedValue)
}
/// var General.Storage.wrappedValue : Swift.Int { get }
/// The value wrapped by this property wrapper, expanded to an [`Swift.Int`].
/// The value wrapped by this property wrapper, expanded to an ``Int``.
public
var wrappedValue:Int
{
.init(self.storage)
}
}
/// struct General.Storage2<I>
/// where I:Swift.FixedWidthInteger & Swift.BinaryInteger
/// @propertyWrapper
/// A property wrapper providing an immutable `(`[`Swift.Int`]`, `[`Swift.Int`]`)`
/// interface backed by a different integer type.
/// # [See also](general-storage-types)
/// ## (general-storage-types)
/// A property wrapper providing an immutable `(```Int```, ```Int```)`
/// interface backed by a different integer type.
@propertyWrapper
public
struct Storage2<I> where I:FixedWidthInteger & BinaryInteger
{
private
var storage:(x:I, y:I)
/// init General.Storage2.init(wrappedValue:)
/// Creates an instance of this property wrapper, with the given values
/// truncated to the width of the storage type [`I`].
/// - wrappedValue : (x:Swift.Int, y:Swift.Int)
/// Creates an instance of this property wrapper, with the given values
/// truncated to the width of the storage type `I`.
///
/// - Parameter wrappedValue:
/// The values to wrap.
public
init(wrappedValue:(x:Int, y:Int))
Expand All @@ -73,40 +57,33 @@ extension General
.init(truncatingIfNeeded: wrappedValue.y)
)
}
/// var General.Storage2.wrappedValue : Swift.Int { get }
/// The values wrapped by this property wrapper, expanded to an
/// `(`[`Swift.Int`]`, `[`Swift.Int`]`)` tuple.
/// The values wrapped by this property wrapper, expanded to an
/// `(```Int```, ```Int```)` tuple.
public
var wrappedValue:(x:Int, y:Int)
{
(.init(self.storage.x), .init(self.storage.y))
}
}
/// struct General.MutableStorage<I>
/// where I:Swift.FixedWidthInteger & Swift.BinaryInteger
/// @propertyWrapper
/// A property wrapper providing a mutable [`Swift.Int`] interface backed
/// by a different integer type.
/// # [See also](general-storage-types)
/// ## (general-storage-types)
/// A property wrapper providing a mutable ``Int`` interface backed
/// by a different integer type.
@propertyWrapper
public
struct MutableStorage<I> where I:FixedWidthInteger & BinaryInteger
{
private
var storage:I
/// init General.MutableStorage.init(wrappedValue:)
/// Creates an instance of this property wrapper, with the given value
/// truncated to the width of the storage type [`I`].
/// - wrappedValue : Swift.Int
/// Creates an instance of this property wrapper, with the given value
/// truncated to the width of the storage type `I`.
///
/// - Parameter wrappedValue:
/// The value to wrap.
public
init(wrappedValue:Int)
{
self.storage = .init(truncatingIfNeeded: wrappedValue)
}
/// var General.MutableStorage.wrappedValue : Swift.Int { get set }
/// The value wrapped by this property wrapper, expanded to an [`Swift.Int`].
/// The value wrapped by this property wrapper, expanded to an ``Int``.
public
var wrappedValue:Int
{
Expand Down Expand Up @@ -305,11 +282,7 @@ extension General.Heap:ExpressibleByArrayLiteral
// 2d iterators
extension General
{
/// struct General.Range2<Bound>
/// where Bound:Swift.Comparable
/// : Swift.Sequence where Bound:Swift.Strideable, Bound.Stride:Swift.SignedInteger
/// A two-dimensional open range.
/// ## (general-range-types)
/// A two-dimensional open range.
public
struct Range2<Bound> where Bound:Comparable
{
Expand All @@ -335,16 +308,10 @@ func ..< <Bound>(lhs:(x:Bound, y:Bound), rhs:(x:Bound, y:Bound)) -> General.Rang

extension General.Range2:Sequence where Bound:Strideable, Bound.Stride:SignedInteger
{
/// typealias General.Range2.Element = (x:Bound, y:Bound)
/// ?: Swift.Sequence where Bound:Swift.Strideable, Bound.Stride:Swift.SignedInteger
public
typealias Element = (x:Bound, y:Bound)

/// struct General.Range2.Iterator
/// ?: Swift.Sequence where Bound:Swift.Strideable, Bound.Stride:Swift.SignedInteger
/// : Swift.IteratorProtocol
/// A two-dimensional range iterator.
/// ## (general-range-types)
/// A two-dimensional range iterator.
public
struct Iterator
{
Expand All @@ -353,16 +320,12 @@ extension General.Range2:Sequence where Bound:Strideable, Bound.Stride:SignedInt
let bound:(x:(Bound, Bound), y:Bound)
}

/// func General.Range2.makeIterator()
/// ?: Swift.Sequence where Bound:Swift.Strideable, Bound.Stride:Swift.SignedInteger
/// Creates an iterator for this range instance.
/// Creates an iterator for this range instance.
///
/// This iterator will traverse the range space in row-major order. For
/// example, if the bounds are `(x: 0, y: 0)` and `(x: 2, y: 2)`, the iterator
/// will yield the elements `(x: 0, y: 0)`, `(x: 1, y: 0)`, `(x: 0, y: 1)`,
/// and `(x: 1, y: 1)`, in that order.
/// - -> : Iterator
/// An iterator.
/// This iterator will traverse the range space in row-major order. For
/// example, if the bounds are `(x: 0, y: 0)` and `(x: 2, y: 2)`, the iterator
/// will yield the elements `(x: 0, y: 0)`, `(x: 1, y: 0)`, `(x: 0, y: 1)`,
/// and `(x: 1, y: 1)`, in that order.
public
func makeIterator() -> Iterator
{
Expand All @@ -372,10 +335,9 @@ extension General.Range2:Sequence where Bound:Strideable, Bound.Stride:SignedInt
}
extension General.Range2.Iterator:IteratorProtocol
{
/// mutating func General.Range2.Iterator.next()
/// ?: Swift.IteratorProtocol
/// Advances to the next element and returns it, or `nil` if no next element exists.
/// - -> : (x:Bound, y:Bound)?
/// Advances to the next element and returns it, or `nil` if no next element exists.
///
/// - Returns:
/// The next element in the two-dimensional range sequence, if it exists,
/// otherwise `nil`. If advancing the `x` index would cause it to reach its
/// upper bound, this iterator will advance to the next `y` index and reset
Expand Down Expand Up @@ -412,12 +374,12 @@ extension General.Range2.Iterator:IteratorProtocol
// raw buffer utilities
extension ArraySlice where Element == UInt8
{
// Loads this array slice as a misaligned big-endian integer value,
// and casts it to a desired format.
// - Parameters:
// - bigEndian: The size and type to interpret this array slice as.
// - type: The type to cast the read integer value to.
// - Returns: The read integer value, cast to `U`.
/// Loads this array slice as a misaligned big-endian integer value,
/// and casts it to a desired format.
/// - Parameters:
/// - bigEndian: The size and type to interpret this array slice as.
/// - type: The type to cast the read integer value to.
/// - Returns: The read integer value, cast to `U`.
func load<T, U>(bigEndian:T.Type, as type:U.Type) -> U
where T:FixedWidthInteger, U:BinaryInteger
{
Expand Down Expand Up @@ -447,13 +409,13 @@ extension ArraySlice where Element == UInt8
}
extension Array where Element == UInt8
{
// Loads a misaligned big-endian integer value from the given byte offset
// and casts it to a desired format.
// - Parameters:
// - bigEndian: The size and type to interpret the data to load as.
// - type: The type to cast the read integer value to.
// - byte: The byte offset to load the big-endian integer from.
// - Returns: The read integer value, cast to `U`.
/// Loads a misaligned big-endian integer value from the given byte offset
/// and casts it to a desired format.
/// - Parameters:
/// - bigEndian: The size and type to interpret the data to load as.
/// - type: The type to cast the read integer value to.
/// - byte: The byte offset to load the big-endian integer from.
/// - Returns: The read integer value, cast to `U`.
func load<T, U>(bigEndian:T.Type, as type:U.Type, at byte:Int) -> U
where T:FixedWidthInteger, U:BinaryInteger
{
Expand All @@ -463,12 +425,12 @@ extension Array where Element == UInt8

extension Array where Element == UInt8
{
// Decomposes the given integer value into its constituent bytes, in big-endian order.
// - Parameters:
// - value: The integer value to decompose.
// - type: The big-endian format `T` to store the given `value` as. The given
// `value` is truncated to fit in a `T`.
// - Returns: An array containing the bytes of the given `value`, in big-endian order.
/// Decomposes the given integer value into its constituent bytes, in big-endian order.
/// - Parameters:
/// - value: The integer value to decompose.
/// - type: The big-endian format `T` to store the given `value` as. The given
/// `value` is truncated to fit in a `T`.
/// - Returns: An array containing the bytes of the given `value`, in big-endian order.
static
func store<U, T>(_ value:U, asBigEndian type:T.Type) -> [UInt8]
where U:BinaryInteger, T:FixedWidthInteger
Expand Down
7 changes: 0 additions & 7 deletions Sources/JPEG/debug.swift
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,8 @@
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at https://mozilla.org/MPL/2.0/. */

// literal forms
extension JPEG.Component.Key:ExpressibleByIntegerLiteral
{
/// init JPEG.Component.Key.init(integerLiteral:)
/// ?: Swift.ExpressibleByIntegerLiteral
/// - integerLiteral : Swift.UInt8
public
init(integerLiteral:UInt8)
{
Expand All @@ -16,9 +12,6 @@ extension JPEG.Component.Key:ExpressibleByIntegerLiteral
}
extension JPEG.Table.Quantization.Key:ExpressibleByIntegerLiteral
{
/// init JPEG.Table.Quantization.Key.init(integerLiteral:)
/// ?: Swift.ExpressibleByIntegerLiteral
/// - integerLiteral : Swift.Int
public
init(integerLiteral:Int)
{
Expand Down
Loading

0 comments on commit 2582ae2

Please sign in to comment.