re-organize folders + update repo metadata

README.md

@@ -1,8 +1,8 @@
 <p align="center">
-    <img src="https://user-images.githubusercontent.com/1342803/36579327-6e8bb73a-1830-11e8-8eb5-c079ac7ecfd2.png" height="64" alt="Engine">
+    <img src="https://user-images.githubusercontent.com/1342803/38834991-185bbaa4-4198-11e8-8b16-a36471e93202.png" height="64" alt="URL-Encoded Form">
     <br>
     <br>
-    <a href="https://docs.vapor.codes/3.0/">
+    <a href="https://docs.vapor.codes/3.0/url-encoded-form/getting-started">
         <img src="http://img.shields.io/badge/read_the-docs-2196f3.svg" alt="Documentation">
     </a>
     <a href="http://vapor.team">
@@ -11,8 +11,8 @@
     <a href="LICENSE">
         <img src="http://img.shields.io/badge/license-MIT-brightgreen.svg" alt="MIT License">
     </a>
-    <a href="https://circleci.com/gh/vapor/engine">
-        <img src="https://circleci.com/gh/vapor/engine.svg?style=shield" alt="Continuous Integration">
+    <a href="https://circleci.com/gh/vapor/url-encoded-form">
+        <img src="https://circleci.com/gh/vapor/url-encoded-form.svg?style=shield" alt="Continuous Integration">
     </a>
     <a href="https://swift.org">
         <img src="http://img.shields.io/badge/swift-4.1-brightgreen.svg" alt="Swift 4.1">

Sources/URLEncodedForm/URLEncodedFormDecoder.swift → Sources/URLEncodedForm/Codable/URLEncodedFormDecoder.swift

@@ -1,17 +1,31 @@
-/// Decodes instances of `Decodable` types from `Data`.
+/// Decodes instances of `Decodable` types from `application/x-www-form-urlencoded` `Data`.
 ///
-///     print(data) /// Data
+///     print(data) // "name=Vapor&age=3"
 ///     let user = try URLEncodedFormDecoder().decode(User.self, from: data)
-///     print(user) /// User
+///     print(user) // User
 ///
+/// URL-encoded forms are commonly used by websites to send form data via POST requests. This encoding is relatively
+/// efficient for small amounts of data but must be percent-encoded.  `multipart/form-data` is more efficient for sending
+/// large data blobs like files.
+///
+/// See [Mozilla's](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) docs for more information about
+/// url-encoded forms.
 public final class URLEncodedFormDecoder: DataDecoder {
     /// The underlying `URLEncodedFormEncodedParser`
     private let parser: URLEncodedFormParser
 
     /// If `true`, empty values will be omitted. Empty values are URL-Encoded keys with no value following the `=` sign.
+    ///
+    ///     name=Vapor&age=
+    ///
+    /// In the above example, `age` is an empty value.
     public var omitEmptyValues: Bool
 
     /// If `true`, flags will be omitted. Flags are URL-encoded keys with no following `=` sign.
+    ///
+    ///     name=Vapor&isAdmin&age=3
+    ///
+    /// In the above example, `isAdmin` is a flag.
     public var omitFlags: Bool
 
     /// Create a new `URLEncodedFormDecoder`.
@@ -29,9 +43,9 @@ public final class URLEncodedFormDecoder: DataDecoder {
 
     /// Decodes an instance of the supplied `Decodable` type from `Data`.
     ///
-    ///     print(data) /// Data
+    ///     print(data) // "name=Vapor&age=3"
     ///     let user = try URLEncodedFormDecoder().decode(User.self, from: data)
-    ///     print(user) /// User
+    ///     print(user) // User
     ///
     /// - parameters:
     ///     - decodable: Generic `Decodable` type (`D`) to decode.

Sources/URLEncodedForm/URLEncodedFormEncoder.swift → Sources/URLEncodedForm/Codable/URLEncodedFormEncoder.swift

@@ -3,15 +3,22 @@
 ///     print(user) /// User
 ///     let data = try URLEncodedFormEncoder().encode(user)
 ///     print(data) /// Data
+///
+/// URL-encoded forms are commonly used by websites to send form data via POST requests. This encoding is relatively
+/// efficient for small amounts of data but must be percent-encoded.  `multipart/form-data` is more efficient for sending
+/// large data blobs like files.
+///
+/// See [Mozilla's](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) docs for more information about
+/// url-encoded forms.
 public final class URLEncodedFormEncoder: DataEncoder {
     /// Create a new `URLEncodedFormEncoder`.
     public init() {}
 
     /// Encodes the supplied `Encodable` object to `Data`.
     ///
-    ///     print(user) /// User
+    ///     print(user) // User
     ///     let data = try URLEncodedFormEncoder().encode(user)
-    ///     print(data) /// Data
+    ///     print(data) // "name=Vapor&age=3"
     ///
     /// - parameters:
     ///     - encodable: Generic `Encodable` object (`E`) to encode.

Sources/URLEncodedForm/URLEncodedFormParser.swift → Sources/URLEncodedForm/Data/URLEncodedFormParser.swift

@@ -197,7 +197,7 @@ private extension Data {
 
 private extension Array {
     /// Accesses an array index or returns `nil` if the array isn't long enough.
-    subscript(safe index: Int) -> Element? {
+    fileprivate subscript(safe index: Int) -> Element? {
         guard index < count else {
             return nil
         }

Sources/URLEncodedForm/URLEncodedFormError.swift → Sources/URLEncodedForm/Utilities/URLEncodedFormError.swift

@@ -1,6 +1,6 @@
 import Debugging
 
-/// Errors thrown while encoding/decoding form-urlencoded data.
+/// Errors thrown while encoding/decoding `application/x-www-form-urlencoded` data.
 public struct URLEncodedFormError: Error, Debuggable {
     /// See Debuggable.identifier
     public let identifier: String