Improve API docs

JWTDecode/DecodeError.swift

@@ -1,36 +1,29 @@
 import Foundation
 
-/**
- A decoding error due to a malformed JWT.
-
- - invalidBase64Url: when either the header or body parts cannot be Base64URL-decoded.
- - invalidJSONValue: when either the decoded header or body is not a valid JSON object.
- - invalidPartCount: when the JWT doesn't have the required amount of parts (header, body, and signature).
- */
+/// A decoding error due to a malformed JWT.
 public enum DecodeError: LocalizedError, CustomDebugStringConvertible {
+    /// When either the header or body parts cannot be Base64URL-decoded.
     case invalidBase64Url(String)
+
+    /// When either the decoded header or body is not a valid JSON object.
     case invalidJSON(String)
-    case invalidPartCount(String, Int)
 
-    /**
-     Description of the error.
+    /// When the JWT doesn't have the required amount of parts (header, body, and signature).
+    case invalidPartCount(String, Int)
 
-     - Important: You should avoid displaying the error description to the user, it's meant for **debugging** only.
-     */
+    /// Description of the error.
+    ///
+    /// - Important: You should avoid displaying the error description to the user, it's meant for **debugging** only.
     public var localizedDescription: String { return self.debugDescription }
 
-    /**
-     Description of the error.
-
-     - Important: You should avoid displaying the error description to the user, it's meant for **debugging** only.
-     */
+    /// Description of the error.
+    ///
+    /// - Important: You should avoid displaying the error description to the user, it's meant for **debugging** only.
     public var errorDescription: String? { return self.debugDescription }
 
-    /**
-     Description of the error.
-
-     - Important: You should avoid displaying the error description to the user, it's meant for **debugging** only.
-     */
+    /// Description of the error.
+    ///
+    /// - Important: You should avoid displaying the error description to the user, it's meant for **debugging** only.
     public var debugDescription: String {
         switch self {
         case .invalidJSON(let value):

JWTDecode/JWT.swift

@@ -1,10 +1,7 @@
 import Foundation
 
-/**
-*  A decoded JWT.
-*
-* - See: [jwt.io](https://jwt.io/)
-*/
+/// A decoded JWT.
+/// See [jwt.io](https://jwt.io/) for more information on JWTs.
 public protocol JWT {
 
     /// Contents of the header part.
@@ -47,23 +44,31 @@ public protocol JWT {
 
 public extension JWT {
 
-    /**
-     Returns a claim by its name.
-
-     - Parameter name: name of the claim in the JWT.
-     - Returns: a ``Claim`` instance.
-     */
+    /// Returns a claim by its name.
+    ///
+    /// ```swift
+    /// if let email = jwt.claim(name: "email").string {
+    ///     print("Email is \(email)")
+    /// }
+    /// ```
+    ///
+    /// - Parameter name: Name of the claim in the JWT.
+    /// - Returns: A ``Claim`` instance.
     func claim(name: String) -> Claim {
         let value = self.body[name]
         return Claim(value: value)
     }
 
-    /**
-     Returns a claim by its name.
-
-     - Parameter claim: name of the claim in the JWT.
-     - Returns: a ``Claim`` instance.
-     */
+    /// Returns a claim by its name.
+    ///
+    /// ```swift
+    /// if let email = jwt["email"].string {
+    ///     print("Email is \(email)")
+    /// }
+    /// ```
+    ///
+    /// - Parameter claim: Name of the claim in the JWT.
+    /// - Returns: A ``Claim`` instance.
     subscript(claim: String) -> Claim {
         return self.claim(name: claim)
     }

JWTDecode/JWTDecode.swift

@@ -1,17 +1,15 @@
 import Foundation
 
-/**
- Decodes a JWT into an object that holds the decoded body, along with the header and signature.
- If the JWT cannot be decoded a ``DecodeError`` will be thrown.
-
- ```
- let jwt = try decode(jwt: idToken)    
- ```
-
- - Parameter jwt: JWT string value to decode.
- - Throws: a ``DecodeError`` error if the JWT cannot be decoded.
- - Returns: a ``JWT`` instance.
- */
+/// Decodes a JWT into an object that holds the decoded body, along with the header and signature.
+///
+/// ```swift
+/// let jwt = try decode(jwt: idToken)
+/// ```
+///
+/// - Parameter jwt: JWT string value to decode.
+/// - Throws: A ``DecodeError`` error if the JWT cannot be decoded.
+/// - Returns: A ``JWT`` value.
+/// - Important: This method doesn't validate the JWT. Any well-formed JWT can be decoded from Base64URL.
 public func decode(jwt: String) throws -> JWT {
     return try DecodedJWT(jwt: jwt)
 }
@@ -51,11 +49,7 @@ struct DecodedJWT: JWT {
     }
 }
 
-/**
- *  A JWT claim.
- *
- * - See: ``JWT``
- */
+/// A JWT claim.
 public struct Claim {
 
     /// Raw claim value.