Improve documentation coverage.

Author: natestedman

.jazzy.yaml

@@ -8,8 +8,8 @@ custom_categories:
     - name: Attribute Functions
       children:
         - AttributeFunction
-        - attribute(_:_:_:)
-        - attributes(_:_:)
+        - attribute(_:withValue:)
+        - attributesWithValues(_:)
 
     - name: Attribute Extensions
       children:

Attributed/AttributedStringConvertible.swift

@@ -12,7 +12,20 @@ import Foundation
 
 // MARK: - Function Types
 
-/// An attribute function.
+/// The type for attribute functions.
+///
+/// All extensions provided by Attributed add functions of this type. For example, an extension of `UIColor` can be used
+/// to create red text:
+///
+///     UIColor.redColor().foregroundAttribute(text)
+///
+/// However, referencing `UIColor.redColor().foregroundAttribute` alone can also be useful, as it is equivalent to an
+/// `AttributeFunction` that applies red text to its parameter. Attribute functions can be used in sequences, which can
+/// be reduced to a single `AttributeFunction` with the `join` extension of `SequenceType`.
+///
+/// If writing code that should compose with Attributed, it typically makes sense to write functions that will apply
+/// attributes in terms of `AttributeFunction`. If additional parameters are required, it's better to return a closure
+/// than to accept an `AttributedStringConvertible` alongside other parameters.
 public typealias AttributeFunction = AttributedStringConvertible -> AttributedStringConvertible
 
 // MARK: - Protocol

Attributed/ColorType+Attributes.swift

@@ -14,6 +14,7 @@
     import AppKit
 #endif
 
+/// `ColorType` is extended to provide foreground, background, underline, and strikethrough color attributes.
 public extension ColorType
 {
     // MARK: - Foreground Color

Attributed/FontType+Attributes.swift

@@ -14,6 +14,7 @@
     import AppKit
 #endif
 
+/// `FontType` is extended to provide an attribute function.
 public extension FontType
 {
     // MARK: - Attributes

Attributed/Ligature+Attributes.swift

@@ -14,6 +14,7 @@
     import AppKit
 #endif
 
+/// `Ligature` is extended to provide an attribute function.
 public extension Ligature
 {
     // MARK: - Attributes

Attributed/Ligature.swift

@@ -14,7 +14,7 @@ public enum Ligature: Int
     /// No ligatures will be used.
     case None = 0
 
-    /// The default ligatures will be used
+    /// The default ligatures will be used.
     case Default = 1
 
     #if os(OSX)

Attributed/NSCursor+Attributes.swift

@@ -12,6 +12,7 @@
 
 import AppKit
 
+/// `NSCursor` is extended to provide an attribute function.
 extension NSCursor
 {
     // MARK: - Attributes

Attributed/NSNumberConvertible+Attributes.swift

@@ -14,6 +14,7 @@
     import AppKit
 #endif
 
+/// `NSNumberConvertible` is extended to provide baseline offset and kerning attribute functions.
 public extension NSNumberConvertible
 {
     // MARK: - Baseline Offset

Attributed/NSNumberConvertible.swift

@@ -18,130 +18,172 @@ import Foundation
 /// Extensions for number-based attributes extend this type.
 public protocol NSNumberConvertible
 {
-    /// The value of the type, as an `NSNumber` instance.
+    /// The value, wrapped in an `NSNumber` instance.
     var NSNumberValue: NSNumber { get }
 }
 
 // MARK: - NSNumber
+
+/// `NSNumber` is extended to conform to `NSNumberConvertible`.
 extension NSNumber: NSNumberConvertible
 {
+    /// Returns `self`.
     public var NSNumberValue: NSNumber
     {
         return self
     }
 }
 
 // MARK: - Int
+
+/// `Int` is extended to conform to `NSNumberConvertible`.
 extension Int: NSNumberConvertible
 {
+    /// The value, wrapped in an `NSNumber` instance.
     public var NSNumberValue: NSNumber
     {
         return self
     }
 }
 
 // MARK: - UInt
+
+/// `UInt` is extended to conform to `NSNumberConvertible`.
 extension UInt: NSNumberConvertible
 {
+    /// The value, wrapped in an `NSNumber` instance.
     public var NSNumberValue: NSNumber
     {
         return self
     }
 }
 
 // MARK: - Int8
+
+/// `Int8` is extended to conform to `NSNumberConvertible`.
 extension Int8: NSNumberConvertible
 {
+    /// The value, wrapped in an `NSNumber` instance.
     public var NSNumberValue: NSNumber
     {
         return Int(self)
     }
 }
 
 // MARK: - UInt8
+
+/// `UInt8` is extended to conform to `NSNumberConvertible`.
 extension UInt8: NSNumberConvertible
 {
+    /// The value, wrapped in an `NSNumber` instance.
     public var NSNumberValue: NSNumber
     {
         return UInt(self)
     }
 }
 
 // MARK: - Int16
+
+/// `Int16` is extended to conform to `NSNumberConvertible`.
 extension Int16: NSNumberConvertible
 {
+    /// The value, wrapped in an `NSNumber` instance.
     public var NSNumberValue: NSNumber
     {
         return Int(self)
     }
 }
 
 // MARK: - UInt16
+
+/// `UInt16` is extended to conform to `NSNumberConvertible`.
 extension UInt16: NSNumberConvertible
 {
+    /// The value, wrapped in an `NSNumber` instance.
     public var NSNumberValue: NSNumber
     {
         return UInt(self)
     }
 }
 
 // MARK: - Int32
+
+/// `Int32` is extended to conform to `NSNumberConvertible`.
 extension Int32: NSNumberConvertible
 {
+    /// The value, wrapped in an `NSNumber` instance.
     public var NSNumberValue: NSNumber
     {
         return Int(self)
     }
 }
 
 // MARK: - UInt32
+
+/// `UInt32` is extended to conform to `NSNumberConvertible`.
 extension UInt32: NSNumberConvertible
 {
+    /// The value, wrapped in an `NSNumber` instance.
     public var NSNumberValue: NSNumber
     {
         return UInt(self)
     }
 }
 
 // MARK: - Int64
+
+/// `Int64` is extended to conform to `NSNumberConvertible`.
 extension Int64: NSNumberConvertible
 {
+    /// The value, wrapped in an `NSNumber` instance.
     public var NSNumberValue: NSNumber
     {
         return NSNumber(longLong: self)
     }
 }
 
 // MARK: - UInt64
+
+/// `UInt64` is extended to conform to `NSNumberConvertible`.
 extension UInt64: NSNumberConvertible
 {
+    /// The value, wrapped in an `NSNumber` instance.
     public var NSNumberValue: NSNumber
     {
         return NSNumber(unsignedLongLong: self)
     }
 }
 
 // MARK: - Float
+
+/// `Float` is extended to conform to `NSNumberConvertible`.
 extension Float: NSNumberConvertible
 {
+    /// The value, wrapped in an `NSNumber` instance.
     public var NSNumberValue: NSNumber
     {
         return self
     }
 }
 
 // MARK: - Double
+
+/// `Double` is extended to conform to `NSNumberConvertible`.
 extension Double: NSNumberConvertible
 {
+    /// The value, wrapped in an `NSNumber` instance.
     public var NSNumberValue: NSNumber
     {
         return self
     }
 }
 
 // MARK: - CGFloat
+
+/// `CGFloat` is extended to conform to `NSNumberConvertible`.
 extension CGFloat: NSNumberConvertible
 {
+    /// The value, wrapped in an `NSNumber` instance.
     public var NSNumberValue: NSNumber
     {
         return self

Attributed/NSParagraphStyle+Attributes.swift

@@ -14,6 +14,7 @@
     import AppKit
 #endif
 
+/// `NSParagraphStyle` is extended to provide an attribute function.
 public extension NSParagraphStyle
 {
     // MARK: - Attributes