Improve comments in code

diff --git a/Sources/arguments_source.swift b/Sources/arguments_source.swift
index d1bf4c607a992e3ce91ad4357531ba965b7f5d8a..9615318d4037f63b000a8d6561648daa0a6075a9 100644 (file)
--- a/Sources/arguments_source.swift
+++ b/Sources/arguments_source.swift
@@ -1,10 +1,13 @@
-/// Source that deals with command line
+// Source that reads track artist and name from the command line

 class ArgumentsSource: Source {
 class ArgumentsSource: Source {

-    public var currentTrack: Track? {
-        if CommandLine.arguments.count >= 3 {

 
 

-            // expected usage: $ ./lyricli <artist> <name>
+    // Returns a track based on the arguments. It assumes the track artist
+    // will be the first argument, and the name will be the second, excluding
+    // any flags.
+    var currentTrack: Track? {

 
 

+        if CommandLine.arguments.count >= 3 {
+            // expected usage: $ ./lyricli <artist> <name>

             let trackName: String = CommandLine.arguments[2]
             let trackArtist: String = CommandLine.arguments[1]
 
             let trackName: String = CommandLine.arguments[2]
             let trackArtist: String = CommandLine.arguments[1]
 

diff --git a/Sources/configuration.swift b/Sources/configuration.swift
index bc217694b1ab189a1748bc3b0d7754f7094bdaf3..f1a1ee1203ac04c5e129d80ff69ab98b96be220a 100644 (file)
--- a/Sources/configuration.swift
+++ b/Sources/configuration.swift
@@ -1,24 +1,23 @@
 import Foundation
 
 import Foundation
 

-/// Handles reading and writing the configuration
-public class Configuration {
-
-    let configurationPath = NSString(string: "~/.lyricli.conf").expandingTildeInPath
-
-    // The defaults are added here
+// Reads and writes the configuration. Config keys are accessed as a dictionary.
+class Configuration {
+    // Location of the global configuration file
+    private let configurationPath = NSString(string: "~/.lyricli.conf").expandingTildeInPath

 
 

+    // Default options, will be automatically written to the global config if
+    // not found.

     private var configuration: [String: Any] =  [
     private var configuration: [String: Any] =  [

-        "enabled_sources": ["arguments"],
-        "default": true
+        "enabled_sources": ["arguments"]

     ]
 
     ]
 

-    static let sharedInstance: Configuration = Configuration()
+    // The shared instance of the object
+    static let shared: Configuration = Configuration()

 
     private init() {
 
 
     private init() {
 

-        // Read the config file and attempt toset any of the values. Otherwise
-        // Don't do anything.
-        // IMPROVEMENT: Enable a debug mode
+        // Read the config file and attempt to set any of the values. Otherwise
+        // don't do anything.

 
         if let data = try? NSData(contentsOfFile: configurationPath) as Data {
             if let parsedConfig = try? JSONSerialization.jsonObject(with: data) {
 
         if let data = try? NSData(contentsOfFile: configurationPath) as Data {
             if let parsedConfig = try? JSONSerialization.jsonObject(with: data) {


@@ -42,6 +41,7 @@ public class Configuration {
         writeConfiguration()
     }
 
         writeConfiguration()
     }
 

+    // Write the configuration back to the file

     private func writeConfiguration() {
 
         var error: NSError?
     private func writeConfiguration() {
 
         var error: NSError?


@@ -56,7 +56,7 @@ public class Configuration {
         }
     }
 
         }
     }
 

-    // Allow access as an object
+    // Allow access to the config properties as a dictionary

     subscript(index: String) -> Any? {
         get {
             return configuration[index]
     subscript(index: String) -> Any? {
         get {
             return configuration[index]

diff --git a/Sources/lyricli.swift b/Sources/lyricli.swift
index 10d9270f541d038314b732b26b92ee0b6fae1120..e7d14b9d416cbf867b3776007a766dbc5bad9fe9 100644 (file)
--- a/Sources/lyricli.swift
+++ b/Sources/lyricli.swift
@@ -1,15 +1,20 @@
-/// The main Lyricli interface
-public class Lyricli {
-    public static var version = "0.0.0"
+// The main class, handles all the actions that the executable will call
+class Lyricli {

 
 

-    public static var showTitle = false
+    // Version of the application
+    static var version = "0.0.0"

 
 

-    public static func printLyrics() {
+    // Flag that controls whether we should show the track artist and name before
+    // the lyrics
+    static var showTitle = false
+
+    // Obtains the name of the current track from a source, fetches the lyrics
+    // from an engine and prints them
+    static func printLyrics() {

 
         let sourceManager = SourceManager()
 
         if let currentTrack = sourceManager.currentTrack {
 
         let sourceManager = SourceManager()
 
         if let currentTrack = sourceManager.currentTrack {

-

             let engine = LyricsEngine(withTrack: currentTrack)
 
             if let lyrics = engine.lyrics {
             let engine = LyricsEngine(withTrack: currentTrack)
 
             if let lyrics = engine.lyrics {


@@ -27,22 +32,28 @@ public class Lyricli {
         }
     }
 
         }
     }
 

-    public static func printSources() {
+    // Print the currently available sources
+    static func printSources() {

         print("Listing Sources: Not yet implemented")
     }
 
         print("Listing Sources: Not yet implemented")
     }
 

-    public static func enableSource(_ sourceName: String) {
+    // Runs the enable method of a source and writes the configuration to set it
+    // as enabled
+    static func enableSource(_ sourceName: String) {

         print("Enable source \(sourceName): Not yet implemented")
     }
 
         print("Enable source \(sourceName): Not yet implemented")
     }
 

-    public static func disableSource(_ sourceName: String) {
+    // Remove a source from the enabled sources configuration
+    static func disableSource(_ sourceName: String) {

         print("Disable source \(sourceName): Not yet implemented")
     }
 
         print("Disable source \(sourceName): Not yet implemented")
     }
 

-    public static func resetSource(_ sourceName: String) {
+    // Removes any configuration for a source, and disables it
+    static func resetSource(_ sourceName: String) {

         print("Reset source \(sourceName): Not yet implemented")
     }
 
         print("Reset source \(sourceName): Not yet implemented")
     }
 

+    // Prints the track artist and name

     private static func printTitle(_ track: Track) {
         print("\(track.artist) - \(track.name)")
     }
     private static func printTitle(_ track: Track) {
         print("\(track.artist) - \(track.name)")
     }

diff --git a/Sources/lyrics_engine.swift b/Sources/lyrics_engine.swift
index 9741a2c63d65393ebeadc27fd63c5d5829455bd7..85e4735eaa00a5027f795285a65b46061d89bcf2 100644 (file)
--- a/Sources/lyrics_engine.swift
+++ b/Sources/lyrics_engine.swift
@@ -1,20 +1,28 @@
 import Foundation
 import HTMLEntities
 
 import Foundation
 import HTMLEntities
 

-/// Looks for lyrics on the internet
+// Given a track, attempts to fetch the lyrics from lyricswiki

 class LyricsEngine {
 
 class LyricsEngine {
 

+    // URL of the API endpoint to use

     private let apiURL = "https://lyrics.wikia.com/api.php?action=lyrics&func=getSong&fmt=realjson"
     private let apiURL = "https://lyrics.wikia.com/api.php?action=lyrics&func=getSong&fmt=realjson"

+
+    // Method used to call the API

     private let apiMethod = "GET"
     private let apiMethod = "GET"

+
+    // Regular expxression used to find the lyrics in the lyricswiki HTML

     private let lyricsMatcher = "class='lyricbox'>(.+)<div"
 
     private let lyricsMatcher = "class='lyricbox'>(.+)<div"
 

+    // The track we'll be looking for

     private let track: Track
 
     // Fetches the lyrics and returns if found
     private let track: Track
 
     // Fetches the lyrics and returns if found

-

     var lyrics: String? {
     var lyrics: String? {

+

         var lyrics: String?
 
         var lyrics: String?
 

+        // Encode the track artist and name and finish building the API call URL
+

         if let artist = track.artist.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) {
             if let name: String = track.name.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) {
                 if let url = URL(string: "\(apiURL)&artist=\(artist)&song=\(name)") {
         if let artist = track.artist.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) {
             if let name: String = track.name.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) {
                 if let url = URL(string: "\(apiURL)&artist=\(artist)&song=\(name)") {


@@ -46,13 +54,14 @@ class LyricsEngine {
         return lyrics
     }
 
         return lyrics
     }
 

+    // Initializes with a track

     init(withTrack targetTrack: Track) {
 
         track = targetTrack
     }
 
     init(withTrack targetTrack: Track) {
 
         track = targetTrack
     }
 

-    // Fetch the lyrics from the API and request / parse the page
-
+    // Fetch the lyrics URL from the API, triggers the request to fetch the
+    // lyrics page

     private func fetchLyricsFromAPI(withURL url: URL, completionHandler: @escaping (String?) -> Void) {
 
         var apiRequest = URLRequest(url: url)
     private func fetchLyricsFromAPI(withURL url: URL, completionHandler: @escaping (String?) -> Void) {
 
         var apiRequest = URLRequest(url: url)


@@ -83,8 +92,7 @@ class LyricsEngine {
         task.resume()
     }
 
         task.resume()
     }
 

-    // Fetch the lyrics from the page and parse the page
-
+    // Fetch the lyrics from the page and send it to the parser

     private func fetchLyricsFromPage(withURL url: URL, completionHandler: @escaping (String?) -> Void) {
 
         var pageRequest = URLRequest(url: url)
     private func fetchLyricsFromPage(withURL url: URL, completionHandler: @escaping (String?) -> Void) {
 
         var pageRequest = URLRequest(url: url)


@@ -107,10 +115,11 @@ class LyricsEngine {
         task.resume()
     }
 
         task.resume()
     }
 

-    // Parses the wiki to obtain the lyrics
-
+    // Parses the wiki to find the lyrics, decodes the lyrics object

     private func parseHtmlBody(_ body: String, completionHandler: @escaping (String?) -> Void) {
 
     private func parseHtmlBody(_ body: String, completionHandler: @escaping (String?) -> Void) {
 

+        // Look for the lyrics lightbox
+

         if let regex = try? NSRegularExpression(pattern: lyricsMatcher) {
             let matches = regex.matches(in: body, range: NSRange(location: 0, length: body.characters.count))
 
         if let regex = try? NSRegularExpression(pattern: lyricsMatcher) {
             let matches = regex.matches(in: body, range: NSRange(location: 0, length: body.characters.count))
 


@@ -131,7 +140,6 @@ class LyricsEngine {
     }
 
     // Escapes the HTML entities
     }
 
     // Escapes the HTML entities

-

     private func decodeLyrics(_ lyrics: String) -> String {
 
         let unescapedLyrics = lyrics.htmlUnescape()
     private func decodeLyrics(_ lyrics: String) -> String {
 
         let unescapedLyrics = lyrics.htmlUnescape()

diff --git a/Sources/main.swift b/Sources/main.swift
index 5c39cb5c591a5650f784da6865e5dac99f644c26..9d46e926fef8b7e1d9bea7721df6405a9b9a9b4f 100644 (file)
--- a/Sources/main.swift
+++ b/Sources/main.swift
@@ -1,7 +1,8 @@
 import CommandLineKit
 import Foundation
 
 import CommandLineKit
 import Foundation
 

-func main() {
+// Entry point of the application. This is the main executable
+private func main() {

     let (flags, parser) = createParser()
 
     do {
     let (flags, parser) = createParser()
 
     do {

diff --git a/Sources/source_manager.swift b/Sources/source_manager.swift
index e55cc8b18ae19e1acc222b442c6be788b21ea09c..5ee1305c9927cb8968ba2aba05b074c19a3c5b17 100644 (file)
--- a/Sources/source_manager.swift
+++ b/Sources/source_manager.swift
@@ -1,10 +1,12 @@
-/// Manages the different sources. Keeps track of them, lists and toggles
+// Collect and manage the available and enabled source

 class SourceManager {
 
 class SourceManager {
 

+    // List of sources enabled for the crurent platform

     private var availableSources: [String: Source] = [
         "arguments": ArgumentsSource()
     ]
 
     private var availableSources: [String: Source] = [
         "arguments": ArgumentsSource()
     ]
 

+    // Iterate over the sources until we find a track or run out of sources

     var currentTrack: Track? {
         for source in enabledSources {
             if let currentTrack = source.currentTrack {
     var currentTrack: Track? {
         for source in enabledSources {
             if let currentTrack = source.currentTrack {


@@ -15,6 +17,7 @@ class SourceManager {
         return nil
     }
 
         return nil
     }
 

+    // Return the list of enabled sources based on the configuration

     var enabledSources: [Source] {
 
         // Checks the config and returns an array of sources based on the
     var enabledSources: [Source] {
 
         // Checks the config and returns an array of sources based on the


@@ -22,7 +25,7 @@ class SourceManager {
 
         var sources = [Source]()
 
 
         var sources = [Source]()
 

-        if let sourceNames = Configuration.sharedInstance["enabled_sources"] as? [String] {
+        if let sourceNames = Configuration.shared["enabled_sources"] as? [String] {

             for sourceName in sourceNames {
                 if let source = availableSources[sourceName] {
                     sources.append(source)
             for sourceName in sourceNames {
                 if let source = availableSources[sourceName] {
                     sources.append(source)


@@ -33,15 +36,15 @@ class SourceManager {
         return sources
     }
 
         return sources
     }
 

+    // Given a source name, it will enable it and add it to the enabled sources config

     func enable(sourceName: String) {
     }
 
     func enable(sourceName: String) {
     }
 

+    // Given a source name, it will remove it from the enabled sources config

     func disable(sourceName: String) {
     }
 
     func disable(sourceName: String) {
     }
 

+    // Given a source name, it removes any stored configuration and disables it

     func reset(sourceName: String) {
     }
     func reset(sourceName: String) {
     }

-
-    func getSources(sourceName: String) {
-    }

 }
 }

diff --git a/Sources/source_protocol.swift b/Sources/source_protocol.swift
index ee9350c1d4cb63ccece7e466361ffa249614a389..0885994d338589b456f5dde7f85b1062c204c844 100644 (file)
--- a/Sources/source_protocol.swift
+++ b/Sources/source_protocol.swift
@@ -1,3 +1,5 @@
+// All sources should comply with this protocol. The currentTrack computed
+// property will return a track if the conditions are met

 protocol Source {
     var currentTrack: Track? { get }
 }
 protocol Source {
     var currentTrack: Track? { get }
 }

diff --git a/Sources/track.swift b/Sources/track.swift
index d2a9047faa6e4a21bce15b0f15fd3711a312135d..ead43591661ad16939e29cd73fda6d1342418e9d 100644 (file)
--- a/Sources/track.swift
+++ b/Sources/track.swift
@@ -1,6 +1,10 @@
-/// Contains the artist and name of a track
+// Holds the name and artist of a track

 class Track {
 class Track {

+
+    // The name of the track to search for

     let name: String
     let name: String

+
+    // The name of the artist

     let artist: String
 
     init(withName trackName: String, andArtist trackArtist: String) {
     let artist: String
 
     init(withName trackName: String, andArtist trackArtist: String) {