mirror of
https://github.com/apple/swift-nio
synced 2026-11-22 04:30:41 +00:00
### Motivation:
Eight doc comments name an argument that the declaration below them does
not have, so DocC has nothing to bind the description to and quietly
drops it. Nothing warns about this: Swift has no equivalent of
`-Wdocumentation`, and DocC stays silent rather than complaining, so
these sit until somebody reads the generated page and wonders where the
description went
| file | the comment says | the declaration says |
|---|---|---|
| `NIOPosix/ServerSocket.swift` | `descriptor` | `socket` |
| `NIOPosix/Socket.swift` ×2 | `descriptor` | `socket` |
| `NIOHTTP1/ByteCollectionUtils.swift` | `bytes` | `to` |
| `NIOHTTP1/HTTPTypes.swift` | `buffer` | `headers` |
| `NIOFS/BufferedStream.swift` ×2 | `sequence` | `element` |
| `NIOFS/SystemFileHandle.swift` | `executor` | `threadPool` |
The socket ones are worth a word. Each of those files has a pair: a
deprecated `init(descriptor:)` and its replacement `init(socket:)`, and
the rename is recorded right there in `@available(*, deprecated,
renamed: "init(socket:setNonBlocking:)")`. The replacement inherited the
wording of the one it replaced, so the doc still says `descriptor`. The
deprecated ones are correct and I left them alone
And the last two are the same defect in two copies of one module,
`NIOFS` and `_NIOFileSystem`, which is what a verbatim copy of a file
does to a mistake inside it. Fixing one and not the other would leave
them out of sync, so both are in here
### Modifications:
Renamed the documented argument to the one in the declaration, eleven
lines across eight files
One is slightly more than a rename: in `ByteBuffer.write(headers:)` the
entry described the buffer the method is called on rather than its
argument, so it now describes `headers` and keeps the note about the
writer index
### Result:
The parameter descriptions reach the generated documentation. No API
change, no behaviour change, comments only
btw these came out of a checker I wrote for exactly this, run over the
tree and then read by hand one by one. Six of the things it flagged
turned out to be my parser rather than your code, and those are fixed on
my side rather than sent to you 🙌🏼
all of it on a MacBook Air M3, of course
75 lines
2.7 KiB
Swift
75 lines
2.7 KiB
Swift
//===----------------------------------------------------------------------===//
|
|
//
|
|
// This source file is part of the SwiftNIO open source project
|
|
//
|
|
// Copyright (c) 2017-2021 Apple Inc. and the SwiftNIO project authors
|
|
// Licensed under Apache License v2.0
|
|
//
|
|
// See LICENSE.txt for license information
|
|
// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
|
|
//
|
|
// SPDX-License-Identifier: Apache-2.0
|
|
//
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
import NIOCore
|
|
|
|
private let defaultWhitespaces = [" ", "\t"].map({ $0.utf8.first! })
|
|
|
|
extension ByteBufferView {
|
|
internal func trim(limitingElements: [UInt8]) -> ByteBufferView {
|
|
guard let lastNonWhitespaceIndex = self.lastIndex(where: { !limitingElements.contains($0) }),
|
|
let firstNonWhitespaceIndex = self.firstIndex(where: { !limitingElements.contains($0) })
|
|
else {
|
|
// This buffer is entirely trimmed elements, so trim it to nothing.
|
|
return self[self.startIndex..<self.startIndex]
|
|
}
|
|
return self[firstNonWhitespaceIndex..<index(after: lastNonWhitespaceIndex)]
|
|
}
|
|
|
|
internal func trimSpaces() -> ByteBufferView {
|
|
trim(limitingElements: defaultWhitespaces)
|
|
}
|
|
}
|
|
|
|
extension Sequence where Self.Element == UInt8 {
|
|
/// Compares the collection of `UInt8`s to a case insensitive collection.
|
|
///
|
|
/// This collection could be get from applying the `UTF8View`
|
|
/// property on the string protocol.
|
|
///
|
|
/// - Parameter to: The string constant in the form of a collection of `UInt8`
|
|
/// - Returns: Whether the collection contains **EXACTLY** this array or no, but by ignoring case.
|
|
internal func compareCaseInsensitiveASCIIBytes<T: Sequence>(to: T) -> Bool
|
|
where T.Element == UInt8 {
|
|
// fast path: we can get the underlying bytes of both
|
|
let maybeMaybeResult = self.withContiguousStorageIfAvailable { lhsBuffer -> Bool? in
|
|
to.withContiguousStorageIfAvailable { rhsBuffer in
|
|
if lhsBuffer.count != rhsBuffer.count {
|
|
return false
|
|
}
|
|
|
|
for idx in 0..<lhsBuffer.count {
|
|
// let's hope this gets vectorised ;)
|
|
if lhsBuffer[idx] & 0xdf != rhsBuffer[idx] & 0xdf {
|
|
return false
|
|
}
|
|
}
|
|
return true
|
|
}
|
|
}
|
|
|
|
if let maybeResult = maybeMaybeResult, let result = maybeResult {
|
|
return result
|
|
} else {
|
|
return self.elementsEqual(to, by: { ($0 & 0xdf) == ($1 & 0xdf) })
|
|
}
|
|
}
|
|
}
|
|
|
|
extension String {
|
|
internal func isEqualCaseInsensitiveASCIIBytes(to: String) -> Bool {
|
|
self.utf8.compareCaseInsensitiveASCIIBytes(to: to.utf8)
|
|
}
|
|
}
|