diff --git a/BNRSwiftJSON/JSON.swift b/BNRSwiftJSON/JSON.swift index 1dce1d64..27176b99 100644 --- a/BNRSwiftJSON/JSON.swift +++ b/BNRSwiftJSON/JSON.swift @@ -6,9 +6,7 @@ // Copyright © 2015 Big Nerd Ranch. Licensed under MIT. // -/** - An enum to describe the structure of JSON. -*/ +/// An enum to describe the structure of JSON. public enum JSON { case Array([JSON]) case Dictionary([Swift.String: JSON]) @@ -23,6 +21,7 @@ public enum JSON { extension JSON { + /// An enum to encapsulate errors that may arise in working with `JSON`. public enum Error: ErrorType { /// The `index` is out of bounds for a JSON array case IndexOutOfBounds(index: Swift.Int) diff --git a/BNRSwiftJSON/JSONDecodable.swift b/BNRSwiftJSON/JSONDecodable.swift index 84cd5bf6..0f1fa64d 100644 --- a/BNRSwiftJSON/JSONDecodable.swift +++ b/BNRSwiftJSON/JSONDecodable.swift @@ -6,12 +6,12 @@ // Copyright © 2015 Big Nerd Ranch. Licensed under MIT. // -/// A protocol to provide functionality of creating a model object with a `JSON` +/// A protocol to provide functionality for creating a model object with a `JSON` /// value. public protocol JSONDecodable { /// Creates an instance of the model with a `JSON` instance. - /// - parameter value: An instance of a `JSON` value from which to + /// - parameter json: An instance of a `JSON` value from which to /// construct an instance of the implementing type. /// - throws: Any `JSON.Error` for errors derived from inspecting the /// `JSON` value, or any other error involved in decoding. @@ -21,6 +21,11 @@ public protocol JSONDecodable { extension Double: JSONDecodable { + /// An initializer to create an instance of `Double` from a `JSON` value. + /// - parameter json: An instance of `JSON`. + /// - throws: The initializer will throw an instance of `JSON.Error` if + /// an instance of `Double` cannot be created from the `JSON` value that was + /// passed to this initializer. public init(json: JSON) throws { switch json { case let .Double(double): @@ -36,6 +41,11 @@ extension Double: JSONDecodable { extension Int: JSONDecodable { + /// An initializer to create an instance of `Int` from a `JSON` value. + /// - parameter json: An instance of `JSON`. + /// - throws: The initializer will throw an instance of `JSON.Error` if + /// an instance of `Int` cannot be created from the `JSON` value that was + /// passed to this initializer. public init(json: JSON) throws { switch json { case let .Double(double): @@ -51,6 +61,11 @@ extension Int: JSONDecodable { extension String: JSONDecodable { + /// An initializer to create an instance of `String` from a `JSON` value. + /// - parameter json: An instance of `JSON`. + /// - throws: The initializer will throw an instance of `JSON.Error` if + /// an instance of `String` cannot be created from the `JSON` value that was + /// passed to this initializer. public init(json: JSON) throws { guard case let .String(string) = json else { throw JSON.Error.ValueNotConvertible(type: Swift.String) @@ -62,6 +77,11 @@ extension String: JSONDecodable { extension Bool: JSONDecodable { + /// An initializer to create an instance of `Bool` from a `JSON` value. + /// - parameter json: An instance of `JSON`. + /// - throws: The initializer will throw an instance of `JSON.Error` if + /// an instance of `Bool` cannot be created from the `JSON` value that was + /// passed to this initializer. public init(json: JSON) throws { guard case let .Bool(bool) = json else { throw JSON.Error.ValueNotConvertible(type: Swift.Bool) @@ -137,14 +157,14 @@ extension JSON { return dictionary } - /// Attempts to decodes many values from a desendant JSON array at a path + /// Attempts to decode many values from a descendant JSON array at a path /// into JSON. /// - parameter type: If the context this method is called from does not /// make the return type clear, pass a type implementing `JSONDecodable` /// to disambiguate the type to decode with. /// - returns: An `Array` of decoded elements /// - throws: Any of the `JSON.Error` cases thrown by `decode(type:)`, as - // well as any error that arises from decoding the contained values. + /// well as any error that arises from decoding the contained values. /// - seealso: `JSON.decode(type:)` public func arrayOf(type type: Decoded.Type = Decoded.self) throws -> [Decoded] { return try array().map { try $0.decode() } diff --git a/BNRSwiftJSON/JSONParsing.swift b/BNRSwiftJSON/JSONParsing.swift index bee39db8..c55ee002 100644 --- a/BNRSwiftJSON/JSONParsing.swift +++ b/BNRSwiftJSON/JSONParsing.swift @@ -35,19 +35,18 @@ extension NSJSONSerialization: JSONParserType { // MARK: Decode NSData /// Use the built-in, Objective-C based JSON parser to create `JSON`. + /// - parameter data: An instance of `NSData`. + /// - returns: An instance of `JSON`. + /// - throws: An error that may arise if the `NSData` cannot be parsed into an object. public static func createJSONFromData(data: NSData) throws -> JSON { return makeJSON(try NSJSONSerialization.JSONObjectWithData(data, options: [])) } // MARK: Make JSON - /** - Makes a `JSON` object by matching its argument to a case in the `JSON` enum. - - :param: object The instance of `AnyObject` returned from serializing the JSON. - - :returns: An instance of `JSON` matching the JSON given to the function. - */ + /// Makes a `JSON` object by matching its argument to a case in the `JSON` enum. + /// - parameter object: The instance of `AnyObject` returned from serializing the JSON. + /// - returns: An instance of `JSON` matching the JSON given to the function. private static func makeJSON(object: AnyObject) -> JSON { switch object { case let n as NSNumber: @@ -72,26 +71,18 @@ extension NSJSONSerialization: JSONParserType { // MARK: Make a JSON Array - /** - Makes a `JSON` array from the object passed in. - - :param: jsonArray The array to transform into a `JSON`. - - :returns: An instance of `JSON` matching the array. - */ + /// Makes a `JSON` array from the object passed in. + /// - parameter jsonArray: The array to transform into a `JSON`. + /// - returns: An instance of `JSON` matching the array. private static func makeJSONArray(jsonArray: [AnyObject]) -> JSON { return .Array(jsonArray.map(makeJSON)) } // MARK: Make a JSON Dictionary - /** - Makes a `JSON` dictionary from the Cocoa dictionary passed in. - - :param: jsonDict The dictionary to transform into `JSON`. - - :returns: An instance of `JSON` matching the dictionary. - */ + /// Makes a `JSON` dictionary from the Cocoa dictionary passed in. + /// - parameter jsonDict: The dictionary to transform into `JSON`. + /// - returns: An instance of `JSON` matching the dictionary. private static func makeJSONDictionary(jsonDict: [Swift.String: AnyObject]) -> JSON { return JSON(jsonDict.lazy.map { (key, value) in (key, makeJSON(value)) @@ -113,11 +104,8 @@ extension JSON { return try NSJSONSerialization.dataWithJSONObject(obj, options: []) } - /** - A function to help with the serialization of `JSON`. - - :returns: An `AnyObject` suitable for `NSJSONSerialization`'s use. - */ + /// A function to help with the serialization of `JSON`. + /// - returns: An `AnyObject` suitable for `NSJSONSerialization`'s use. private func toNSJSONSerializationObject() -> AnyObject { switch self { case .Array(let jsonArray): diff --git a/BNRSwiftJSON/JSONSequences.swift b/BNRSwiftJSON/JSONSequences.swift index 5ab9e54d..543b327f 100644 --- a/BNRSwiftJSON/JSONSequences.swift +++ b/BNRSwiftJSON/JSONSequences.swift @@ -8,9 +8,10 @@ extension SequenceType { - /// Map a failable `transform` over `self`, capturing all transformations. - /// - returns: Two arrays of the transformations that succeeded and failed, - /// respectively. + /// Map a failable `transform` over `self`, capturing all transformations + /// into either an array of successes or failures. + /// - parameter transform: A `throws`ing function that transforms an `Element` into a `T`. + /// - returns: A tuple of two arrays, one for successes and one for failures. /// - complexity: O(N). public func mapAndPartition(@noescape transform: (Self.Generator.Element) throws -> T) -> (successes: [T], failures: [ErrorType]) { var successes = [T]()