Add some documentation

Sources/CryptoSwift/Authenticator.swift

@@ -6,7 +6,8 @@
 //  Copyright (c) 2014 Marcin Krzyzanowski. All rights reserved.
 //
 
+/// Message authentication code.
 public protocol Authenticator {
-    /// Generates an authenticator for message using a one-time key and returns the 16-byte result
+    /// Calculate Message Authentication Code (MAC) for message.
     func authenticate(_ bytes: Array<UInt8>) throws -> Array<UInt8>
 }

Sources/CryptoSwift/Checksum.swift

@@ -6,6 +6,7 @@
 //  Copyright (c) 2014 Marcin Krzyzanowski. All rights reserved.
 //
 
+/// CRC - cyclic redundancy check code.
 public final class Checksum {
     private static let table32:Array<UInt32> = [0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, 0x706af48f, 0xe963a535, 0x9e6495a3,
         0x0edb8832, 0x79dcb8a4, 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, 0x90bf1d91,
@@ -97,10 +98,25 @@ public final class Checksum {
 
 //MARK: Public interface
 public extension Checksum {
-    static func crc32(_ message:Array<UInt8>, seed: UInt32? = nil, reflect : Bool = true) -> UInt32 {
+
+    /// Calculate CRC32
+    ///
+    /// - parameter message: Message
+    /// - parameter seed:    Seed value (Optional)
+    /// - parameter reflect: is reflect (default true)
+    ///
+    /// - returns: Calculated code
+    static func crc32(_ message:Array<UInt8>, seed: UInt32? = nil, reflect: Bool = true) -> UInt32 {
         return Checksum().crc32(message, seed: seed, reflect: reflect)
     }
 
+
+    /// Calculate CRC16
+    ///
+    /// - parameter message: Message
+    /// - parameter seed:    Seed value (Optional)
+    ///
+    /// - returns: Calculated code
     static func crc16(_ message:Array<UInt8>, seed: UInt16? = nil) -> UInt16 {
         return Checksum().crc16(message, seed: seed)
     }

Sources/CryptoSwift/Cryptors.swift

@@ -12,6 +12,7 @@
     import Darwin
 #endif
 
+/// Worker cryptor/decryptor of `Updatable` types
 public protocol Cryptors: class {
     associatedtype EncryptorType: Updatable
     associatedtype DecryptorType: Updatable

Sources/CryptoSwift/Digest.swift

@@ -9,27 +9,47 @@
 @available(*, deprecated:0.6.0, renamed: "Digest")
 public typealias Hash = Digest
 
+/// Hash functions to calculate Digest.
 public struct Digest {
+
+    /// Calculate MD5 Digest
+    /// - parameter bytes: input message
+    /// - returns: Digest bytes
     public static func md5(_ bytes: Array<UInt8>) -> Array<UInt8> {
         return MD5().calculate(for: bytes)
     }
 
+    /// Calculate SHA1 Digest
+    /// - parameter bytes: input message
+    /// - returns: Digest bytes
     public static func sha1(_ bytes: Array<UInt8>) -> Array<UInt8> {
         return SHA1(bytes).calculate()
     }
 
+    /// Calculate SHA2-224 Digest
+    /// - parameter bytes: input message
+    /// - returns: Digest bytes
     public static func sha224(_ bytes: Array<UInt8>) -> Array<UInt8> {
         return SHA2(bytes, variant: .sha224).calculate32()
     }
 
+    /// Calculate SHA2-256 Digest
+    /// - parameter bytes: input message
+    /// - returns: Digest bytes
     public static func sha256(_ bytes: Array<UInt8>) -> Array<UInt8> {
         return SHA2(bytes, variant: .sha256).calculate32()
     }
 
+    /// Calculate SHA2-384 Digest
+    /// - parameter bytes: input message
+    /// - returns: Digest bytes
     public static func sha384(_ bytes: Array<UInt8>) -> Array<UInt8> {
         return SHA2(bytes, variant: .sha384).calculate64()
     }
 
+    /// Calculate SHA2-512 Digest
+    /// - parameter bytes: input message
+    /// - returns: Digest bytes
     public static func sha512(_ bytes: Array<UInt8>) -> Array<UInt8> {
         return SHA2(bytes, variant: .sha512).calculate64()
     }

Sources/CryptoSwift/Poly1305.swift

@@ -7,9 +7,8 @@
 //
 //  http://tools.ietf.org/html/draft-agl-tls-chacha20poly1305-04#section-4
 //
-//  Poly1305 takes a 32-byte, one-time key and a message and produces a 16-byte tag that authenticates the
-//  message such that an attacker has a negligible chance of producing a valid tag for an inauthentic message.
-
+///  Poly1305 takes a 32-byte, one-time key and a message and produces a 16-byte tag that authenticates the
+///  message such that an attacker has a negligible chance of producing a valid tag for an inauthentic message.
 final public class Poly1305: Authenticator {
 
     public enum Error: Swift.Error {
@@ -76,7 +75,8 @@ final public class Poly1305: Authenticator {
             }
         }
     }
-    
+
+    /// - parameter key: 32-byte key
     public init (key: Array<UInt8>) {
         ctx = Context(key)
     }
@@ -279,10 +279,9 @@ final public class Poly1305: Authenticator {
      Calculate Message Authentication Code (MAC) for message.
      Calculation context is discarder on instance deallocation.
 
-     - parameter key:     256-bit key
-     - parameter message: Message
+     - parameter bytes: Message
 
-     - returns: Message Authentication Code
+     - returns: 16-byte tag that authenticates the message
      */
     public func authenticate(_ bytes:Array<UInt8>) throws -> Array<UInt8> {
         guard let ctx = self.ctx else {

Sources/CryptoSwift/RandomAccessCryptor.swift

@@ -6,7 +6,12 @@
 //  Copyright © 2016 Marcin Krzyzanowski. All rights reserved.
 //
 
+/// Random access cryptor
 public protocol RandomAccessCryptor: Updatable {
-    /// Seek to position in file. Usable if block mode allows random access.
+    /// Seek to position in file, if block mode allows random access.
+    ///
+    /// - parameter to: new value of counter
+    ///
+    /// - returns: true if seek succeed
     @discardableResult mutating func seek(to: Int) -> Bool
 }

Sources/CryptoSwift/SecureBytes.swift

@@ -5,9 +5,6 @@
 //  Created by Marcin Krzyzanowski on 15/04/16.
 //  Copyright © 2016 Marcin Krzyzanowski. All rights reserved.
 //
-//  SecureBytes keeps bytes in memory. Because this is class, bytes are not copied
-//  and memory area is locked as long as referenced, then unlocked on deinit
-//
 
 #if os(Linux)
     import Glibc
@@ -15,6 +12,8 @@
     import Darwin
 #endif
 
+///  Keeps bytes in memory. Because this is class, bytes are not copied
+///  and memory area is locked as long as referenced, then unlocked on deinit
 final class SecureBytes {
     private let bytes: Array<UInt8>
     let count: Int

Sources/CryptoSwift/String+Extension.swift

@@ -41,14 +41,17 @@ extension String {
         return self.utf8.lazy.map({ $0 as UInt8 }).crc16(seed: seed).bytes().toHexString()
     }
 
-    /// Returns hex string of bytes
+
+    /// - parameter cipher: Instance of `Cipher`
+    /// - returns: hex string of bytes
     public func encrypt(cipher: Cipher) throws -> String {
         return try self.utf8.lazy.map({ $0 as UInt8 }).encrypt(cipher: cipher).toHexString()
     }
 
     // decrypt() does not make sense for String
 
-    /// Returns hex string of bytes
+    /// - parameter authenticator: Instance of `Authenticator`
+    /// - returns: hex string of string
     public func authenticate<A: Authenticator>(with authenticator: A) throws -> String {
         return try self.utf8.lazy.map({ $0 as UInt8 }).authenticate(with: authenticator).toHexString()
     }

Sources/CryptoSwift/Updatable.swift

@@ -8,6 +8,8 @@
 //  TODO: Consider if Updatable shoud use Collection rather than Sequence
 //
 
+/// A type that supports incremental updates. For example Digest or Cipher may be updatable
+/// and calculate result incerementally.
 public protocol Updatable {
     /// Update given bytes in chunks.
     ///