From 469451b7b78baa663198f11a5f168b6ecb0dac49 Mon Sep 17 00:00:00 2001
From: Danny Moesch <danny.moesch@icloud.com>
Date: Sun, 2 Dec 2018 16:55:35 +0100
Subject: [PATCH] Move parts of the documentation into the TokenBuilder class

---
 passKit/Models/Password.swift     | 37 ++++++++++++-------------------
 passKit/Parser/TokenBuilder.swift | 17 ++++++++++++++
 2 files changed, 31 insertions(+), 23 deletions(-)

diff --git a/passKit/Models/Password.swift b/passKit/Models/Password.swift
index bfb9b0b..a85af37 100644
--- a/passKit/Models/Password.swift
+++ b/passKit/Models/Password.swift
@@ -121,29 +121,19 @@ public class Password {
         return additions.first(where: { toLowercase($0.title) == toLowercase(key) })?.content
     }
     
-    /*
-     Set otpType and otpToken, if we are able to construct a valid token.
-     
-     Example of TOTP otpauth
-     (Key Uri Format: https://github.com/google/google-authenticator/wiki/Key-Uri-Format)
-     otpauth://totp/totp-secret?secret=AAAAAAAAAAAAAAAA&issuer=totp-secret
-     
-     Example of TOTP fields [Legacy, lower priority]
-     otp_secret: secretsecretsecretsecretsecretsecret
-     otp_type: totp
-     otp_algorithm: sha1 (default: sha1, optional)
-     otp_period: 30 (default: 30, optional)
-     otp_digits: 6 (default: 6, optional)
-     
-     Example of HOTP fields [Legacy, lower priority]
-     otp_secret: secretsecretsecretsecretsecretsecret
-     otp_type: hotp
-     otp_counter: 1
-     otp_digits: 6 (default: 6, optional)
-     
-     */
+    /// Set the OTP token if we are able to construct a valid one.
+    ///
+    /// Example of TOTP otpauth:
+    ///
+    ///     otpauth://totp/totp-secret?secret=AAAAAAAAAAAAAAAA&issuer=totp-secret
+    ///
+    /// See also [Key Uri Format](https://github.com/google/google-authenticator/wiki/Key-Uri-Format).
+    ///
+    /// In case no otpauth is given in the password file, try to construct the token from separate fields using a
+    /// `TokenBuilder`. This means that tokens provided as otpauth have higher priority.
+    ///
     private func updateOtpToken() {
-        // get otpauth, if we are able to generate a token, return
+        // Get otpauth. If we are able to generate a token, return.
         if var otpauthString = getAdditionValue(withKey: Constants.OTPAUTH, caseSensitive: true) {
             if !otpauthString.hasPrefix("\(Constants.OTPAUTH):") {
                 otpauthString = "\(Constants.OTPAUTH):\(otpauthString)"
@@ -153,7 +143,8 @@ public class Password {
                 return
             }
         }
-        
+
+        // Construct OTP token from separate fields provided in the password file.
         otpToken = TokenBuilder()
             .usingName(name)
             .usingSecret(getAdditionValue(withKey: Constants.OTP_SECRET))
diff --git a/passKit/Parser/TokenBuilder.swift b/passKit/Parser/TokenBuilder.swift
index c577ec1..b0de614 100644
--- a/passKit/Parser/TokenBuilder.swift
+++ b/passKit/Parser/TokenBuilder.swift
@@ -9,6 +9,23 @@
 import Base32
 import OneTimePassword
 
+/// Help building an OTP token from given data.
+///
+/// There is currently support TOTP and HOTP tokens:
+///
+/// * Necessary TOTP data
+///   * secret: `secretsecretsecretsecretsecretsecret`
+///   * type: `totp`
+///   * algorithm: `sha1` (default: `sha1`, optional)
+///   * period: `30` (default: `30`, optional)
+///   * digits: `6` (default: `6`, optional)
+///
+/// * Necessary HOTP data
+///   * secret: `secretsecretsecretsecretsecretsecret`
+///   * type: `hotp`
+///   * counter: `1`
+///   * digits: `6` (default: `6`, optional)
+///
 class TokenBuilder {
 
     private var name: String = ""