add near complete documentation

Sources/StudentVue/Extensions/CharacterSet+numbers.swift

@@ -1,14 +1,16 @@
 //
 //  CharacterSet+numbers.swift
-//  
+//  StudentVue
 //
 //  Created by TheMoonThatRises on 3/18/23.
 //
 
 import Foundation
 
 extension CharacterSet {
-    public static let numbers = CharacterSet(charactersIn: "0123456789").inverted
+    /// A `CharacterSet` disallowing all numerical values.
+    internal static let numbers = CharacterSet(charactersIn: "0123456789").inverted
 
-    public static let numbersextended = CharacterSet(charactersIn: "0123456789/-.").inverted
+    /// A `CharacterSet` disallowing all numerical values along with some other symbols.
+    internal static let numbersextended = CharacterSet(charactersIn: "0123456789/-.").inverted
 }

Sources/StudentVue/Extensions/Date+deserialize.swift

@@ -1,6 +1,6 @@
 //
 //  Date+deserialize.swift
-//  
+//  StudentVue
 //
 //  Created by TheMoonThatRises on 4/12/23.
 //
@@ -9,13 +9,14 @@ import Foundation
 import SWXMLHash
 
 extension Date: XMLValueDeserialization {
-    /// Allows for deserialization of dates from an XML element
+    /// Allows for deserialization of dates from an `XMLElement`.
     ///
-    /// - Parameter element: XMLElement where the date is parsed
+    /// - Parameter element: `XMLElement` where the date is parsed.
     ///
-    /// - Throws: `XMLDeserializationError.typeConversionFailed` Unable to convert XMLElement to Date
+    /// - Throws: `XMLDeserializationError.typeConversionFailed` when unable to convert
+    ///           `XMLElement` to `Date`.
     ///
-    /// - Returns: Date converted from XMLElement
+    /// - Returns: `Date` converted from `XMLElement`.
     public static func deserialize(_ element: XMLHash.XMLElement) throws -> Date {
         let date = stringToDate(element.text)
 
@@ -26,13 +27,14 @@ extension Date: XMLValueDeserialization {
         return validDate
     }
 
-    /// Allows for deserialization of dates from an XML attribute
+    /// Allows for deserialization of dates from an `XMLAttribute`.
     ///
-    /// - Parameter attribute: XMLAttribute where the date is parsed
+    /// - Parameter attribute: `XMLAttribute` where the date is parsed.
     ///
-    /// - Throws: `XMLDeserializationError.typeConversionFailed` Unable to convert XMLAttribute to Date
+    /// - Throws: `XMLDeserializationError.typeConversionFailed` when unable to convert
+    ///           `XMLAttribute` to `Date`.
     ///
-    /// - Returns: Date converted from XMLAttribute
+    /// - Returns: `Date` converted from `XMLAttribute`.
     public static func deserialize(_ attribute: XMLAttribute) throws -> Date {
         let date = stringToDate(attribute.text)
 

Sources/StudentVue/Extensions/Date+stringToDate.swift

@@ -1,6 +1,6 @@
 //
-//  File.swift
-//  
+//  Date+stringToDate.swift
+//  StudentVue
 //
 //  Created by TheMoonThatRises on 4/16/23.
 //
@@ -9,14 +9,21 @@ import Foundation
 import SWXMLHash
 
 extension Date {
-    /// Formats of dates StudentVue returns
-    private static let decodeDateFormats = ["MM/dd/yy", "MM/dd/yy HH:mm:ss", "MM/dd/yy HH:mm:ss a", "yyyy-MM-dd'T'HH:mm:ss", "HH:mm a"]
+    /// Formats of dates StudentVue returns.
+    private static let decodeDateFormats = [
+        "MM/dd/yy",
+        "MM/dd/yy HH:mm:ss",
+        "MM/dd/yy HH:mm:ss a",
+        "yyyy-MM-dd'T'HH:mm:ss",
+        "HH:mm a"
+    ]
 
-    /// Converts String to Date using a defined array of date formats
+    /// Converts `String` to `Date` using a defined array of date formats.
     ///
-    /// - Parameter dateAsString: The date to be converted as a string
+    /// - Parameter dateAsString: The date to be converted as a string.
     ///
-    /// - Returns: Date converted from a string
+    /// - Returns: `Date` converted from a s`String` or `nil` if the input is
+    ///            not an accepted formatted.
     public static func stringToDate(_ dateAsString: String) -> Date? {
         let dateFormatter = DateFormatter()
 

Sources/StudentVue/Extensions/String+PercentEncoding.swift

@@ -1,20 +1,19 @@
 //
 //  String+PercentEncoding.swift
-//
+//  StudentVue
 //
 //  Created by TheMoonThatRises on 3/9/23.
 //
 
 import Foundation
 
 extension String {
-    /// Percent encode if possible
+    /// Percent encode `String.self` for an input of valid characters if possible.
     ///
-    /// - Parameters:
-    ///    - withAllowedCharacters: Set of characters to encode
+    /// - Parameter withAllowedCharacters: Set of characters to encode.
     ///
-    /// - Returns: String percent encoded with character set
-    func percentEncoding(withAllowedCharacters: CharacterSet) -> String {
+    /// - Returns: String percent encoded with character set.
+    internal func percentEncoding(withAllowedCharacters: CharacterSet) -> String {
         self.addingPercentEncoding(withAllowedCharacters: withAllowedCharacters) ?? self
     }
 }

Sources/StudentVue/Extensions/String+replacing.swift

@@ -1,32 +1,33 @@
 //
 //  String+replacing.swift
-//
+//  StudentVue
 //
 //  Created by TheMoonThatRises on 8/9/23.
 //
 
 import Foundation
 
 extension String {
-    /// Replace substring with another substring in the current string
+    /// Replace substring with another substring in the current string.
     ///
     /// - Parameters:
-    ///    - from: Substring of characters to replace
-    ///    - with: Substring of replacing characters
+    ///    - from: Substring of characters to replace.
+    ///    - with: Substring of replacing characters.
     ///
-    /// - Returns: String with substring replaced
-    public func replacing(_ from: String, with: String) -> Self {
+    /// - Returns: String with substring replaced.
+    internal func replacing(_ from: String, with: String) -> Self {
         self.replacingOccurrences(of: from, with: with)
     }
 
-    /// Matches current string with a regex and returns all matches
-    /// https://stackoverflow.com/a/34460111
+    /// Matches current string with a regex and returns all matches.
     ///
-    /// - Parameters:
-    ///    - regex: Regex to match the current string
+    /// This function is taken from
+    /// [https://stackoverflow.com/a/34460111](https://stackoverflow.com/a/34460111).
+    ///
+    /// - Parameter regex: Regex to match the current string.
     ///
-    /// - Returns: An array of matched strings
-    public func matches(_ regex: String) -> [Self] {
+    /// - Returns: An array of matched strings.
+    internal func matches(_ regex: String) -> [Self] {
         do {
             let regex = try NSRegularExpression(pattern: regex)
             let results = regex.matches(in: self,

Sources/StudentVue/Extensions/String+unescape.swift

@@ -1,26 +1,29 @@
 //
 //  String+unescape.swift
-//  
+//  StudentVue
 //
 //  Created by TheMoonThatRises on 4/11/23.
 //
 
 import Foundation
 
 extension String {
-    /// Unescapes left and right angle brackets
-    var unescape: String {
+    /// Unescapes left and right angle brackets.
+    internal var unescape: String {
         let characters = [
 //            "&": "&",
             "&lt;": "<",
             "&gt;": ">"
 //            "&quot;": "\\\"",
 //            "&apos;": "'"
         ]
+
         var str = self
+
         for (escaped, unescaped) in characters {
             str = str.replacingOccurrences(of: escaped, with: unescaped, options: .literal, range: nil)
         }
+
         return str
     }
 }

Sources/StudentVue/Extensions/XMLHash+parse.swift

@@ -1,6 +1,6 @@
 //
 //  XMLHash+parse.swift
-//  
+//  StudentVue
 //
 //  Created by TheMoonThatRises on 4/14/23.
 //
@@ -9,16 +9,27 @@ import Foundation
 import SWXMLHash
 
 public extension XMLHash {
-    static fileprivate let errorAttributes = ["ERROR_MESSAGE", "errorMessage"]
+    /// Attributes SOAP messages include when an error has occured.
+    static private let errorAttributes = ["ERROR_MESSAGE", "errorMessage"]
 
-    /// Wrapper of XMLHash parse function
+    /// Wrapper of XMLHash parse function.
     ///
-    /// - Parameter soapString: The SOAP XML to parse
+    /// This function loops through all of the first layer of children in the requests looking
+    /// for an attribute that is defined in `errorAttributes`. This attribute is then read and
+    /// throws an error. ``StudentVueApi/StudentVueErrors/invalidCredentials`` is the only specific
+    /// error message thrown. Other messages are thrown through a generic
+    /// ``StudentVueApi/StudentVueErrors/soapError(_:)`` with the error message
+    /// as the string value.
     ///
-    /// - Throws: `StudentVueErrors.soapError` An error was returned by the StudentVue API
+    /// - Note: This function may be ineffecient as it loops through all of the first layer
+    ///         of the returned XML.
     ///
-    /// - Returns: An XMLIndexer with only the body of the SOAP response
-    class func parse(soapString: String) throws -> XMLIndexer {
+    /// - Parameter soapString: The SOAP XML to parse.
+    ///
+    /// - Throws: ``StudentVueErrors/soapError`` when an error was returned by StudentVue's API.
+    ///
+    /// - Returns: An XMLIndexer with only the body of the SOAP response.
+    static internal func parse(soapString: String) throws -> XMLIndexer {
         let request = parse(soapString)["soap:Envelope"]["soap:Body"]["ProcessWebServiceRequestMultiWebResponse"]["ProcessWebServiceRequestMultiWebResult"]
 
         do {

Sources/StudentVue/SOAPApi/Models/Attendance.swift

@@ -1,6 +1,6 @@
 //
 //  Attendance.swift
-//  
+//  StudentVue
 //
 //  Created by TheMoonThatRises on 4/13/23.
 //
@@ -10,15 +10,34 @@ import SWXMLHash
 
 extension StudentVueApi {
     public struct AbsencePeriod: XMLObjectDeserialization {
+        /// The period the student was absent.
         public var period: Int
+
+        /// Unknown.
         public var name: String
+
+        /// The reason the student was absent.
         public var reason: String
+
+        /// The course the student was absent from.
         public var course: String
+
+        /// The teacher of the class the student was absent from.
         public var teacher: String
+
+        /// The email of the teacher.
         public var teacherEmail: String
+
+        /// Unknown.
         public var iconName: String
+
+        /// The name of the school.
         public var schoolName: String
+
+        /// The GU of the teacher of the class.
         public var teacherGU: String
+
+        /// The GU year the absence occured.
         public var orgYearGU: String
 
         public static func deserialize(_ element: XMLIndexer) throws -> AbsencePeriod {
@@ -36,12 +55,25 @@ extension StudentVueApi {
     }
 
     public struct Absence: XMLObjectDeserialization {
+        /// The date of the absence.
         public var date: Date
+
+        /// The reason of the absence.
         public var reason: String
+
+        /// The note of the absence.
         public var note: String
+
+        /// Unkown.
         public var dailyIconName: String
+
+        /// Unknown.
         public var codeAllDayReasonType: String
+
+        /// Unknown.
         public var codeAllDayDescription: String
+
+        /// List of periods the student was absent from.
         public var absencePeriods: [AbsencePeriod]
 
         public static func deserialize(_ element: XMLIndexer) throws -> Absence {
@@ -66,7 +98,10 @@ extension StudentVueApi {
     }
 
     public struct ConcurrentSchoolsList: XMLObjectDeserialization {
+        /// Name of the school the student is going to in addition to their primary school.
         public var concurrentSchoolName: String
+
+        /// GU of the year for the concurrent school.
         public var concurrentOrgYearGU: String
 
         public static func deserialize(_ element: XMLIndexer) throws -> ConcurrentSchoolsList {
@@ -76,17 +111,40 @@ extension StudentVueApi {
     }
 
     public struct Attendance: XMLObjectDeserialization {
+        /// Unkown.
         public var type: String
+
+        /// Unknown.
         public var startPeriod: Int
+
+        /// Unkown.
         public var endPeriod: Int
+
+        /// Unkown.
         public var periodCount: Int
+
+        /// Name of the school.
         public var schoolName: String
+
+        /// List of all absences.
         public var absences: [Absence]
+
+        /// List of excused absences.
         public var totalExcused: [AttendancePeriodTotal]
+
+        /// List of tardies.
         public var totalTardies: [AttendancePeriodTotal]
+
+        /// List of unexcused absences.
         public var totalUnexcused: [AttendancePeriodTotal]
+
+        /// List of excused absences due to an activity.
         public var totalActivities: [AttendancePeriodTotal]
+
+        /// List of unexcused tardies.
         public var totalUnexcusedTardies: [AttendancePeriodTotal]
+
+        /// List of schools the student is concurrently attending.
         public var concurrentSchoolsLists: [ConcurrentSchoolsList]
 
         public static func deserialize(_ element: XMLIndexer) throws -> Attendance {