 
 // MARK: - UnitConvertible
 
+/**
+ Ability to convert between units.
+ */
 public protocol UnitConvertible {
+    
+    /**
+     Converts `amount` to a interconvertible `unit`.
+     
+     - parameter amount: given `amount` in the `current unit`
+     - parameter to: given destination `unit`
+     
+     - returns: `amount` converted to given `unit`
+     */
     func convert(amount: NSNumber, to: Unit) -> NSNumber
+    
+    /***/
     func convert(amount: NSNumber, from: Unit) -> NSNumber
+    
+    /***/
     func convert(amount: NSNumber, from: Unit, to: Unit) -> NSNumber
+    
+    /**
+     Indicates if a `unit` is convertible with given `unit`.
+     */
     func isConvertible(with: Unit) -> Bool
 }
 
 extension Unit: UnitConvertible {
 
+    /***/
     public func convert(amount: NSNumber, to: Unit) -> NSNumber {
         return self.convert(amount, from: self, to: to)
     }
 
+    /***/
     public func convert(amount: NSNumber, from: Unit) -> NSNumber {
         return self.convert(amount, from: from, to: self)
     }
 
+    /***/
     public func convert(amount: NSNumber, from: Unit, to: Unit) -> NSNumber {
         let baseAmount = from.convertToBaseUnit(amount)
         let converted = to.convertFromBaseUnit(baseAmount)
         return converted
     }
 
+    /***/
     public func isConvertible(with: Unit) -> Bool {
         return with.dynamicType == self.dynamicType
     }


import Foundation

public class Unit {
    public let name: String
    public let symbol: String
    public let ratio: NSDecimalNumber

    public init(name: String, symbol: String, ratio: NSNumber) {
        self.name = name
        self.symbol = symbol
        self.ratio = NSDecimalNumber(decimal: ratio.decimalValue)
    }

    public func convertFromBaseUnit(amount: NSNumber) -> NSNumber {
        let converted = NSDecimalNumber(decimal: amount.decimalValue)
        return converted.decimalNumberByDividingBy(self.ratio)
    }

    public func convertToBaseUnit(amount: NSNumber) -> NSNumber {
        let converted = NSDecimalNumber(decimal: amount.decimalValue)
        return converted.decimalNumberByMultiplyingBy(self.ratio)

// MARK: - Equatable

extension Unit: Equatable {
    
    /**
     Compares instance to a conforming type.
     
     - parameter other: given `unit` to compare
     - returns:
     */
    public func equals(other: Unit) -> Bool {
        if other.dynamicType !== self.dynamicType {
            return false
