Added header documentation to (most) public interfaces (#27)

Fixes #25

Sources/Jay/Conversions.swift

@@ -11,23 +11,27 @@ import Foundation
 //Useful methods for easier manipulation of type-safe JSON
 
 extension JSON {
-
+
+    /// Returns the `JSON` as `[String: JSON]` if valid, else `nil`.
     public var dictionary: [Swift.String: JSON]? {
         guard case .object(let dict) = self else { return nil }
         return dict
     }
-
+
+    /// Returns the `JSON` as `[JSON]` if valid, else `nil`.
     public var array: [JSON]? {
         guard case .array(let arr) = self else { return nil }
         return arr
     }
-
+
+    /// Returns the `JSON` as an `Int` if valid, else `nil`.
     public var int: Int? {
         guard case .number(let number) = self else { return nil }
         guard case .integer(let jsonInt) = number else { return nil }
         return jsonInt
     }
-
+
+    /// Returns the `JSON` as a `UInt` if valid, else `nil`.
     public var uint: UInt? {
         guard case .number(let number) = self else { return nil }
         switch number {
@@ -36,7 +40,8 @@ extension JSON {
         default: return nil
         }
     }
-
+
+    /// Returns the `JSON` as a `Double` if valid, else `nil`.
     public var double: Double? {
         guard case .number(let number) = self else { return nil }
         switch number {
@@ -45,17 +50,20 @@ extension JSON {
         case .unsignedInteger(let uint): return Double(uint)
         }
     }
-
+
+    /// Returns the `JSON` as a `String` if valid, else `nil`.
     public var string: Swift.String? {
         guard case .string(let str) = self else { return nil }
         return str
     }
-
+
+    /// Returns the `JSON` as a `Bool` if valid, else `nil`.
     public var boolean: Bool? {
         guard case .boolean(let bool) = self else { return nil }
         return bool
     }
-
+
+    /// Returns the `JSON` as `NSNull` if valid, else `nil`.
     public var null: NSNull? {
         guard case .null = self else { return nil }
         return NSNull()
@@ -65,32 +73,43 @@ extension JSON {
 //Thanks for the inspiration for the following initializers, https://github.com/Zewo/JSON/blob/master/Source/JSON.swift
 
 extension JSON: BooleanLiteralConvertible {
+
+    /// Create a `JSON` instance initialized to the provided `booleanLiteral`.
     public init(booleanLiteral value: BooleanLiteralType) {
         self = .boolean(value)
     }
 }
 
 extension JSON: IntegerLiteralConvertible {
+
+    /// Create a `JSON` instance initialized to the provided `integerLiteral`.
     public init(integerLiteral value: IntegerLiteralType) {
         self = .number(.integer(value))
     }
 }
 
 extension JSON: FloatLiteralConvertible {
+
+    /// Create a `JSON` instance initialized to the provided `floatLiteral`.
     public init(floatLiteral value: FloatLiteralType) {
         self = .number(.double(value))
     }
 }
 
 extension JSON: StringLiteralConvertible {
+
+    /// Create a `JSON` instance initialized to the provided `unicodeScalarLiteral`.
     public init(unicodeScalarLiteral value: Swift.String) {
         self = .string(value)
     }
-
+
+    /// Create a `JSON` instance initialized to the provided `extendedGraphemeClusterLiteral`.
     public init(extendedGraphemeClusterLiteral value: Swift.String) {
         self = .string(value)
     }
-
+
+
+    /// Create a `JSON` instance initialized to the provided `stringLiteral`.
     public init(stringLiteral value: StringLiteralType) {
         self = .string(value)
     }

Sources/Jay/Extensions.swift

@@ -13,6 +13,9 @@
 #endif
 
 extension JChar {
+
+    /// Returns a `String` from an array of `JChar`s.
+    /// - Throws: `Error` when parsing the string fails.
     public func string() throws -> String {
         return try [self].string()
     }
@@ -33,7 +36,9 @@ extension String {
 }
 
 extension Collection where Iterator.Element == UInt8 {
-
+
+    /// Returns a `String` from a collection with element `UInt8`.
+    /// - Throws: `Error` when parsing the string fails.
     public func string() throws -> String {
         var utf = UTF8()
         var gen = self.makeIterator()

Sources/Jay/Jay.swift

@@ -9,59 +9,80 @@
 //Implemented from scratch based on http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf and https://www.ietf.org/rfc/rfc4627.txt
 
 public struct Jay {
-
+
+    /// The formatting to apply to the `JSON`.
     public enum Formatting {
         case minified
         case prettified
     }
-
+
+    /// The formatting used.
     public let formatting: Formatting
-
+
+    /// Initializes and returns the `Jay` object.
+    /// - Parameter formatting: The `Formatting` to use. Defaults to `.minified`.
     public init(formatting: Formatting = .minified) {
         self.formatting = formatting
     }
 
-    //Parses data into a dictionary [String: Any] or array [Any].
-    //Does not allow fragments. Test by conditional
-    //casting whether you received what you expected.
-    //Throws a descriptive error in case of any problem.
+    /// Parses data into a dictionary `[String: Any]` or array `[Any]`.
+    /// - Note: Does not allow fragments. Test by conditional
+    /// casting whether you received what you expected.
+    /// - Throws: A descriptive error in case of any problem.
     public func jsonFromData(_ data: [UInt8]) throws -> Any {
         return try NativeParser().parse(data)
     }
-
+
+    /// Parses the reader to `Any`.
+    /// - Throws: A descriptive error in case of any problem.
     public func jsonFromReader(_ reader: Reader) throws -> Any {
         return try NativeParser().parse(reader)
     }
 
-    //Formats your JSON-compatible object into data or throws an error.
+    /// Formats your JSON-compatible object into data.
+    /// - Throws: A descriptive error in case of any problem.
     public func dataFromJson(_ json: JaySON) throws -> [UInt8] {
         return try self.dataFromAnyJson(json.json)
     }
-
+
+    /// Outputs the data from json to the provided stream.
+    /// - Throws: A descriptive error in case of any problem.
     public func dataFromJson(_ json: JaySON, output: JsonOutputStream) throws {
         try self.dataFromAnyJson(json.json, output: output)
     }
 
+    /// Parses the json to data.
+    /// - Throws: A descriptive error in case of any problem.
     public func dataFromJson(_ json: [String: Any]) throws -> [UInt8] {
         return try self.dataFromAnyJson(json)
     }
 
+    /// Outputs the data from json to the provided stream.
+    /// - Throws: A descriptive error in case of any problem.
     public func dataFromJson(_ json: [String: Any], output: JsonOutputStream) throws {
         try self.dataFromAnyJson(json, output: output)
     }
 
+    /// Parses the json to data.
+    /// - Throws: A descriptive error in case of any problem.
     public func dataFromJson(_ json: [Any]) throws -> [UInt8] {
         return try self.dataFromAnyJson(json)
     }
 
+    /// Outputs the data from json to the provided stream.
+    /// - Throws: A descriptive error in case of any problem.
     public func dataFromJson(_ json: [Any], output: JsonOutputStream) throws {
         try self.dataFromAnyJson(json, output: output)
     }
 
+    /// Parses the json to data.
+    /// - Throws: A descriptive error in case of any problem.
     public func dataFromJson(_ json: Any) throws -> [UInt8] {
         return try self.dataFromAnyJson(json)
     }
 
+    /// Outputs the data from json to the provided stream.
+    /// - Throws: A descriptive error in case of any problem.
     public func dataFromJson(_ json: Any, output: JsonOutputStream) throws {
         try self.dataFromAnyJson(json, output: output)
     }
@@ -121,25 +142,34 @@ extension Jay.Formatting {
 //Typesafe
 extension Jay {
 
-    //Allows users to get the JSON representation in a typesafe matter.
-    //However these types are wrapped, so the user is responsible for
-    //manually unwrapping each value recursively. If you just want
-    //Swift types with less type-information, use `jsonFromData()` above.
+    /// Allows users to get the `JSON` representation in a typesafe matter.
+    /// However, these types are wrapped, so the user is responsible for
+    /// manually unwrapping each value recursively.
+    /// - SeeAlso: If you just want Swift types with less
+    /// type-information, use `jsonFromData()` above.
     public func typesafeJsonFromData(_ data: [UInt8]) throws -> JSON {
         return try Parser().parseJsonFromData(data)
     }
-
+
+    /// Allows users to get the `JSON` representation in a typesafe matter.
+    /// However, these types are wrapped, so the user is responsible for
+    /// manually unwrapping each value recursively.
+    /// - SeeAlso: If you just want Swift types with less
+    /// type-information, use `jsonFromReader()` above.
     public func typesafeJsonFromReader(_ reader: Reader) throws -> JSON {
         return try Parser().parseJsonFromReader(reader)
     }
 
-    //Formats your JSON-compatible object into data or throws an error.
+    /// Formats your JSON-compatible object into data.
+    /// - Throws: A descriptive error in case of any problem.
     public func dataFromJson(json: JSON) throws -> [UInt8] {
         let output = ByteArrayOutputStream()
         try dataFromJson(json: json, output: output)
         return output.bytes
     }
-
+
+    /// Outputs your JSON-compatible object as data to the provided stream.
+    /// - Throws: A descriptive error in case of any problem.
     public func dataFromJson(json: JSON, output: JsonOutputStream) throws {
         try json.format(to: output, with: formatting.formatter())
     }

Sources/Jay/NativeTypeConversions.swift

@@ -13,9 +13,17 @@ public struct JaySON {
 }
 
 extension JaySON {
+
+    /// Construct an instance representing the provided `NSDictionary`.
     public init(_ dict: NSDictionary) { self.json = dict }
+
+    /// Construct an instance representing the provided `NSArray`.
     public init(_ array: NSArray) { self.json = array }
+
+    /// Construct an instance representing the provided `[String: Any]`-dictionary.
     public init(_ dict: [String: Any]) { self.json = dict }
+
+    /// Construct an instance representing the provided `[Any]`-array.
     public init(_ array: [Any]) { self.json = array }
 }
 

Sources/Jay/OutputStream.swift

@@ -28,6 +28,7 @@ public class ConsoleOutputStream: JsonOutputStream {
 
     public init() { }
 
+    /// Writes the textual representation of the provided bytes into the standard output.
     public func print(_ bytes: [UInt8]) {
         let str = try? bytes.string()
         Swift.print(str ?? "UNFORMATTABLE DATA", terminator: "")