From dabef818d3c158ce47eba3540b8a9da0fb31e6da Mon Sep 17 00:00:00 2001 From: Peter Adams <63288215+PeterAdams-A@users.noreply.github.com> Date: Fri, 12 Aug 2022 15:31:17 +0100 Subject: [PATCH] Simple index pages for docc (#170) Motivation: An index page ties all the other documentation together Modifications: Add index pages for the library targets. Correct a few minor errors in the main docs. Result: A more joined up documentation experience. --- Sources/NIOExtras/Docs.docc/Article.md | 13 ------ Sources/NIOExtras/Docs.docc/index.md | 43 +++++++++++++++++++ Sources/NIOExtras/WritePCAPHandler.swift | 2 +- Sources/NIOHTTPCompression/Docs.docc/index.md | 27 ++++++++++++ .../HTTPDecompression.swift | 1 + Sources/NIOSOCKS/Docs.docc/index.md | 35 +++++++++++++++ 6 files changed, 107 insertions(+), 14 deletions(-) delete mode 100644 Sources/NIOExtras/Docs.docc/Article.md create mode 100644 Sources/NIOExtras/Docs.docc/index.md create mode 100644 Sources/NIOHTTPCompression/Docs.docc/index.md create mode 100644 Sources/NIOSOCKS/Docs.docc/index.md diff --git a/Sources/NIOExtras/Docs.docc/Article.md b/Sources/NIOExtras/Docs.docc/Article.md deleted file mode 100644 index ed5c0a4a..00000000 --- a/Sources/NIOExtras/Docs.docc/Article.md +++ /dev/null @@ -1,13 +0,0 @@ -# Article - -Summary - -## Overview - -Text - -## Topics - -### Group - -- ``Symbol`` diff --git a/Sources/NIOExtras/Docs.docc/index.md b/Sources/NIOExtras/Docs.docc/index.md new file mode 100644 index 00000000..1790bb99 --- /dev/null +++ b/Sources/NIOExtras/Docs.docc/index.md @@ -0,0 +1,43 @@ +# ``NIOExtras`` + +A collection of helpful utilities to assist in building and debugging Swift-NIO based applications. + +## Overview + +A collection of helpful utilities to assist in building and debugging Swift-NIO based applications. Topics covered include packet capture, the logging of channel pipeline events, frame decoding of various common forms and helpful data types. + +Debugging aids include `ChannelHandler`s to log channel pipeline events both inbound and outbound; and a `ChannelHandler` to log data in packet capture format. + +To support encoding and decoding helpers are provided for data frames which have fixed length; are new line terminated; contain a length prefix; or are defined by a `context-length` header. + +To help simplify building a robust pipeline the ``ServerQuiescingHelper`` makes it easy to collect all child `Channel`s that a given server `Channel` accepts. + +Easy request response flows can be built using the ``RequestResponseHandler`` which takes a request and a promise which is fulfilled when an expected response is received. + +## Topics + +### Debugging Aids + +- ``DebugInboundEventsHandler`` +- ``DebugOutboundEventsHandler`` +- ``NIOWritePCAPHandler`` +- ``NIOPCAPRingBuffer`` + +### Encoding and Decoding + +- ``FixedLengthFrameDecoder`` +- ``NIOJSONRPCFraming`` +- ``LengthFieldBasedFrameDecoder`` +- ``NIOLengthFieldBasedFrameDecoderError`` +- ``LengthFieldPrepender`` +- ``LengthFieldPrependerError`` +- ``LineBasedFrameDecoder`` +- ``NIOExtrasErrors`` +- ``NIOExtrasError`` + +### Channel Pipeline Aids +- ``ServerQuiescingHelper`` +- ``RequestResponseHandler`` + +### Data Types +- ``NIOLengthFieldBitLength`` diff --git a/Sources/NIOExtras/WritePCAPHandler.swift b/Sources/NIOExtras/WritePCAPHandler.swift index 8ace0bb8..92bcf4ec 100644 --- a/Sources/NIOExtras/WritePCAPHandler.swift +++ b/Sources/NIOExtras/WritePCAPHandler.swift @@ -184,7 +184,7 @@ public class NIOWritePCAPHandler: RemovableChannelHandler { private var localAddress: SocketAddress? private var remoteAddress: SocketAddress? - /// Reusable header for `. pcap` file. + /// Reusable header for `.pcap` file. public static var pcapFileHeader: ByteBuffer { var buffer = ByteBufferAllocator().buffer(capacity: 24) buffer.writePCAPHeader() diff --git a/Sources/NIOHTTPCompression/Docs.docc/index.md b/Sources/NIOHTTPCompression/Docs.docc/index.md new file mode 100644 index 00000000..40067107 --- /dev/null +++ b/Sources/NIOHTTPCompression/Docs.docc/index.md @@ -0,0 +1,27 @@ +# ``NIOHTTPCompression`` + +Automatic compression and decompression of HTTP data. + +## Overview + +Channel handlers to support automatic compression and decompression of HTTP data. Add the handlers to your pipeline to support the features you need. + +`Content-Encoding`, `Content-Length`, and `accept-encoding` HTTP headers are set and respected where appropriate. + +Be aware that this works best if there is sufficient data written between flushes. This also performs compute on the event loop thread which could impact performance. + +## Topics + +### Client Channel Handlers + +- ``NIOHTTPRequestCompressor`` +- ``NIOHTTPResponseDecompressor`` + +### Server Channel Handlers +- ``NIOHTTPRequestDecompressor`` +- ``HTTPResponseCompressor`` + +### Compression Methods + +- ``NIOCompression`` +- ``NIOHTTPDecompression`` diff --git a/Sources/NIOHTTPCompression/HTTPDecompression.swift b/Sources/NIOHTTPCompression/HTTPDecompression.swift index 9bf6b51a..e4531d3a 100644 --- a/Sources/NIOHTTPCompression/HTTPDecompression.swift +++ b/Sources/NIOHTTPCompression/HTTPDecompression.swift @@ -15,6 +15,7 @@ import CNIOExtrasZlib import NIOCore +/// Namespace for decompression code. public enum NIOHTTPDecompression { /// Specifies how to limit decompression inflation. public struct DecompressionLimit { diff --git a/Sources/NIOSOCKS/Docs.docc/index.md b/Sources/NIOSOCKS/Docs.docc/index.md new file mode 100644 index 00000000..6b28057e --- /dev/null +++ b/Sources/NIOSOCKS/Docs.docc/index.md @@ -0,0 +1,35 @@ +# ``NIOSOCKS`` + +SOCKS v5 protocol implementation + +## Overview + +An implementation of SOCKS v5 protocol. See [RFC1928](https://www.rfc-editor.org/rfc/rfc1928). + +Add the appropriate channel handler to the start of your channel pipeline to use this protocol. + +For an example see the NIOSOCKSClient target. + +## Topics + +### Channel Handlers +- ``SOCKSClientHandler`` +- ``SOCKSServerHandshakeHandler`` + +### Client Messages +- ``ClientMessage`` +- ``ClientGreeting`` +- ``SOCKSRequest`` + +### Server Messages +- ``ServerMessage`` +- ``SelectedAuthenticationMethod`` +- ``SOCKSResponse`` + +### Supporting Types +- ``AuthenticationMethod`` +- ``SOCKSServerReply`` +- ``SOCKSCommand`` +- ``SOCKSAddress`` +- ``SOCKSProxyEstablishedEvent`` +- ``SOCKSError``