Convert some comments to documentation

code/cli/munki/shared/updatecheck/autoconfig.swift

@@ -19,15 +19,15 @@
 import Foundation
 import SystemConfiguration
 
+/// Uses SystemConfiguration to get the current DNS search domains
 func getSearchDomains() -> [String]? {
     let dnsConfig = SCDynamicStoreCopyValue(nil, "State:/Network/Global/DNS" as CFString)
     return (dnsConfig as? NSDictionary)?["SearchDomains"] as? [String]
 }
 
+/// Tries a few default URLs and returns the first one that doesn't fail
+/// utterly, or the default
 func guessRepoURL() -> String {
-    // Tries a few default URLs and returns the first one that doesn't fail
-    // utterly, or the default
-
     guard let searchDomains = getSearchDomains() else {
         return DEFAULT_INSECURE_REPO_URL
     }
@@ -53,10 +53,9 @@ func guessRepoURL() -> String {
     return DEFAULT_INSECURE_REPO_URL
 }
 
+/// If Munki repo URL is not defined, (or is the insecure default) attempt to
+/// discover one. If successful, record the discovered URL in Munki's preferences.
 func autodetectRepoURLIfNeeded() {
-    // If Munki repo URL is not defined, (or is the insecure default) attempt
-    // to discover one. If successful, record the discovered URL in Munki's
-    // preferences.
     if let softwareRepoURL = pref("SoftwareRepoURL") as? String,
        !softwareRepoURL.isEmpty,
        softwareRepoURL != DEFAULT_INSECURE_REPO_URL

code/cli/munki/shared/updatecheck/installationstate.swift

@@ -26,12 +26,12 @@ enum InstallationState: Int {
     case newerVersionInstalled = 2
 }
 
+/// Checks to see if the item described by pkginfo (or a newer version) is
+/// currently installed
+///
+/// All tests must pass to be considered installed.
+/// Returns InstallationState
 func installedState(_ pkginfo: PlistDict) async -> InstallationState {
-    // Checks to see if the item described by pkginfo (or a newer version) is
-    // currently installed
-
-    // All tests must pass to be considered installed.
-    // Returns InstallationState
     var foundNewer = false
     if pkginfo["OnDemand"] as? Bool ?? false {
         // we always need to install these items
@@ -155,8 +155,8 @@ func installedState(_ pkginfo: PlistDict) async -> InstallationState {
     return .thisVersionInstalled
 }
 
+/// Checks to see if some version of a pkgitem is installed.
 func someVersionInstalled(_ pkginfo: PlistDict) async -> Bool {
-    // Checks to see if some version of a pkgitem is installed.
     if pkginfo["OnDemand"] as? Bool ?? false {
         // These should never be counted as installed
         displayDebug1("This is an OnDemand item.")
@@ -217,12 +217,12 @@ func someVersionInstalled(_ pkginfo: PlistDict) async -> Bool {
     return true
 }
 
+/// Checks to see if there is any evidence that the item described
+/// by pkginfo (any version) is currenly installed.
+/// If any tests pass, the item might be installed.
+/// This is used when determining if we can remove the item, thus
+/// the attention given to the uninstall method.
 func evidenceThisIsInstalled(_ pkginfo: PlistDict) async -> Bool {
-    // Checks to see if there is any evidence that the item described
-    // by pkginfo (any version) is currenly installed.
-    // If any tests pass, the item might be installed.
-    // This is used when determining if we can remove the item, thus
-    // the attention given to the uninstall method.
     if pkginfo["OnDemand"] as? Bool ?? false {
         // These should never be counted as installed
         displayDebug1("This is an OnDemand item.")

code/cli/munki/shared/updatecheck/licensing.swift

@@ -18,9 +18,9 @@
 
 import Foundation
 
+/// Records # of available seats for each optional install
+/// returns an updated list of optional_installs with license info
 func updateAvailableLicenseSeats(_ optionalInstalls: [PlistDict]) -> [PlistDict] {
-    // Records # of available seats for each optional install
-    // returns an updated list of optional_installs with license info
     guard let licenseInfoURL = pref("LicenseInfoURL") as? String else {
         // nothing to do
         return optionalInstalls

code/cli/munki/shared/updatecheck/selfservice.swift

@@ -18,13 +18,13 @@
 
 import Foundation
 
+/// Returns path to "system" SelfServeManifest/
 func selfServiceManifestPath() -> String {
-    // Returns path to "system" SelfServeManifest
     return managedInstallsDir(subpath: "manifests/SelfServeManifest")
 }
 
+/// Updates the SelfServeManifest from a user-writable copy if it exists.
 func updateSelfServeManifest() {
-    // Updates the SelfServeManifest from a user-writable copy if it exists.
     let userManifest = "/Users/Shared/.SelfServeManifest"
     let systemManifest = selfServiceManifestPath()
     if pathIsSymlink(userManifest) {
@@ -57,9 +57,9 @@ func updateSelfServeManifest() {
     }
 }
 
+/// Process a default installs item. Potentially add it to managed_installs
+/// in the SelfServeManifest
 func processDefaultInstalls(_ defaultItems: [String]) {
-    // Process a default installs item. Potentially add it to managed_installs
-    // in the SelfServeManifest
     let selfServeManifest = selfServiceManifestPath()
     var manifest = PlistDict()
     if pathExists(selfServeManifest) {
@@ -103,10 +103,9 @@ func processDefaultInstalls(_ defaultItems: [String]) {
     }
 }
 
+/// Removes any already-removed items from the SelfServeManifest's
+/// managed_uninstalls (So the user can later install them again if they wish)
 func cleanUpSelfServeManagedUninstalls(_ installInfoRemovals: [PlistDict]) {
-    // Removes any already-removed items from the SelfServeManifest's
-    // managed_uninstalls (So the user can later install them again if they
-    // wish)
     let selfServeManifest = selfServiceManifestPath()
     if !pathExists(selfServeManifest) {
         // nothing to do

code/cli/munki/shared/updatecheck/updatecheck.swift

@@ -18,9 +18,8 @@
 
 import Foundation
 
+/// Download display icons for optional installs and active installs/removals
 func downloadIconsForActiveItems(_ installInfo: PlistDict) {
-    // download display icons for optional installs
-    // and active installs/removals
     var itemList = [PlistDict]()
     for key in ["optional_installs", "managed_installs", "removals", "problem_items"] {
         itemList += installInfo[key] as? [PlistDict] ?? []
@@ -31,14 +30,13 @@ func downloadIconsForActiveItems(_ installInfo: PlistDict) {
     downloadIcons(itemList)
 }
 
+/// clean up cache dir
+/// remove any item in the cache that isn't scheduled to be used for
+/// an install or removal
+/// this could happen if an item is downloaded on one updatecheck run,
+/// but later removed from the manifest before it is installed or removed
+/// -- so the cached itemis no longer needed.
 func cleanUpDownloadCache(_ installInfo: PlistDict) {
-    // clean up cache dir
-    // remove any item in the cache that isn't scheduled
-    // to be used for an install or removal
-    // this could happen if an item is downloaded on one
-    // updatecheck run, but later removed from the manifest
-    // before it is installed or removed - so the cached item
-    // is no longer needed.
     let managedInstalls = installInfo["managed_installs"] as? [PlistDict] ?? []
     let removals = installInfo["removals"] as? [PlistDict] ?? []
     let problemItems = installInfo["problem_items"] as? [PlistDict] ?? []
@@ -92,8 +90,8 @@ func cleanUpDownloadCache(_ installInfo: PlistDict) {
     }
 }
 
+/// processes the LocalOnlyManifest if defined and present
 func processLocalOnlyManifest(catalogList: [String], installInfo: inout PlistDict) async throws {
-    // processes the LocalOnlyManifest if defined and present
     guard let localOnlyManifestName = stringPref("LocalOnlyManifest"),
           !localOnlyManifestName.isEmpty,
           !catalogList.isEmpty
@@ -140,9 +138,8 @@ func processLocalOnlyManifest(catalogList: [String], installInfo: inout PlistDic
     }
 }
 
+/// processes the SelfServeManifest if present/
 func processSelfServeManifest(mainManifest: PlistDict, installInfo: inout PlistDict) async throws {
-    // processes the SelfServeManifest if present
-
     guard let parentCatalogs = mainManifest["catalogs"] as? [String] else {
         displayError("Primary manifest has no catalogs")
         return
@@ -230,10 +227,9 @@ enum UpdateCheckResult: Int {
     case updatesAvailable = 1
 }
 
+/// Checks for available new or updated managed software, downloading installer items if needed.
+/// Returns UpdateCheckResult.
 func checkForUpdates(clientID: String? = nil, localManifestPath: String? = nil) async throws -> UpdateCheckResult {
-    // Checks for available new or updated managed software, downloading
-    // installer items if needed. Returns UpdateCheckResult.
-
     // Auto-detect a Munki repo if one isn't defined in preferences
     autodetectRepoURLIfNeeded()