 
 import Foundation
 
+/// A `Generator` contains all of the parameters needed to generate a one-time password.
 public struct Generator: Equatable {
+
+    /// The moving factor, either timer- or counter-based.
     public let factor: Factor
+
+    /// The secret shared between the client and server.
     public let secret: NSData
+
+    /// The cryptographic hash function used to generate the password.
     public let algorithm: Algorithm
+
+    /// The number of digits in the password.
     public let digits: Int
 
+    /**
+    Initializes a new password generator with the given parameters, if valid.
+
+    :param: factor      The moving factor
+    :param: secret      The shared secret
+    :param: algorithm   The cryptographic hash function (defaults to SHA-1)
+    :param: digits      The number of digits in the password (defaults to 6)
+
+    :returns: A valid password generator, or `nil` if the parameters are invalid.
+    */
     public init?(factor: Factor, secret: NSData, algorithm: Algorithm = .SHA1, digits: Int = 6) {
         if !validateGenerator(factor, secret, algorithm, digits) {
             return nil

}

public extension Generator {
    var password: String? {
        if !validateGenerator(factor, secret, algorithm, digits) { return nil }
        let counter = counterForGeneratorWithFactor(self.factor, atTimeIntervalSince1970: NSDate().timeIntervalSince1970)

        self.digits = digits
    }

    /**
    A moving factor with which a generator produces different one-time passwords over time.
    
    Counter:
      Indicates a HOTP, with an associated 8-byte counter value for the moving factor. After
      each use of the password generator, the counter should be incremented to stay in sync with
      the server.
    Timer:
      Indicates a TOTP, with an associated time interval for calculating the time-based moving
      factor. This period value remains constant, and is used as a divisor for the number of
      seconds since the Unix epoch.
    */
    public enum Factor: Equatable {
        case Counter(UInt64)
        case Timer(period: NSTimeInterval)
    }

    /// A cryptographic hash function used to calculate the HMAC from which a password is derived.
    /// The supported algorithms are SHA-1, SHA-256, and SHA-512
    public enum Algorithm: Equatable {
        case SHA1, SHA256, SHA512
    }
