Small grammar and sytax fixes to inline docs.

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)

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<Decoded: JSONDecodable>(type type: Decoded.Type = Decoded.self) throws -> [Decoded] {
         return try array().map { try $0.decode() }

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):

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<T>(@noescape transform: (Self.Generator.Element) throws -> T) -> (successes: [T], failures: [ErrorType]) {
         var successes = [T]()