Merge pull request #598 from kevin51jiang/TheRoadToAProperJavadoc

The Road to Javadoc, Part 1: Prithee, peace

src/main/java/com/rarchives/ripme/App.java

@@ -33,13 +33,22 @@ import com.rarchives.ripme.utils.Utils;
 
 /**
  * Entry point to application.
+ * This is where all the fun happens, with the main method.
  * Decides to display UI or to run silently via command-line.
+ * 
+ * As the "controller" to all other classes, it parses command line parameters and loads the history.
  */
 public class App {
 
     public static final Logger logger = Logger.getLogger(App.class);
     private static final History HISTORY = new History();
 
+    /**
+     * Where everything starts. Takes in, and tries to parse as many commandline arguments as possible.
+     * Otherwise, it launches a GUI.
+     * 
+     * @param args Array of command line arguments.
+     */
     public static void main(String[] args) throws MalformedURLException {
         CommandLine cl = getArgs(args);
 
@@ -74,7 +83,8 @@ public class App {
     /**
      * Creates an abstract ripper and instructs it to rip.
      * @param url URL to be ripped
-     * @throws Exception
+     * @throws Exception Nothing too specific here, just a catch-all.
+     * 
      */
     private static void rip(URL url) throws Exception {
         AbstractRipper ripper = AbstractRipper.getRipper(url);
@@ -89,6 +99,7 @@ public class App {
     private static void handleArguments(String[] args) {
         CommandLine cl = getArgs(args);
 
+        //Help (list commands)
         if (cl.hasOption('h') || args.length == 0) {
             HelpFormatter hf = new HelpFormatter();
             hf.printHelp("java -jar ripme.jar [OPTIONS]", getOptions());
@@ -98,28 +109,34 @@ public class App {
         Utils.configureLogger();
         logger.info("Initialized ripme v" + UpdateUtils.getThisJarVersion());
 
+        //Allow file overwriting
         if (cl.hasOption('w')) {
             Utils.setConfigBoolean("file.overwrite", true);
         }
 
+        //SOCKS proxy server
         if (cl.hasOption('s')) {
             String sservfull = cl.getOptionValue('s').trim();
             Proxy.setSocks(sservfull);
         }
 
+        //HTTP proxy server
         if (cl.hasOption('p')) {
             String proxyserverfull = cl.getOptionValue('p').trim();
             Proxy.setHTTPProxy(proxyserverfull);
         }
 
+        //Number of threads
         if (cl.hasOption('t')) {
             Utils.setConfigInteger("threads.size", Integer.parseInt(cl.getOptionValue('t')));
         }
 
+        //Ignore 404
         if (cl.hasOption('4')) {
             Utils.setConfigBoolean("errors.skip404", true);
         }
 
+        //Re-rip <i>all</i> previous albums
         if (cl.hasOption('r')) {
             // Re-rip all via command-line
             List<String> history = Utils.getConfigList("download.history");
@@ -142,6 +159,7 @@ public class App {
             System.exit(0);
         }
 
+        //Re-rip all <i>selected</i> albums
         if (cl.hasOption('R')) {
             loadHistory();
             if (HISTORY.toList().isEmpty()) {
@@ -174,24 +192,29 @@ public class App {
             }
         }
 
+        //Save the order of images in album
         if (cl.hasOption('d')) {
             Utils.setConfigBoolean("download.save_order", true);
         }
 
+        //Don't save the order of images in album
         if (cl.hasOption('D')) {
             Utils.setConfigBoolean("download.save_order", false);
         }
 
+        //In case specify both, break and exit since it isn't possible.
         if ((cl.hasOption('d'))&&(cl.hasOption('D'))) {
             logger.error("\nCannot specify '-d' and '-D' simultaneously");
             System.exit(-1);
         }
 
+        //Destination directory
         if (cl.hasOption('l')) {
             // change the default rips directory
             Utils.setConfigString("rips.directory", cl.getOptionValue('l'));
         }
 
+        //Read URLs from File
         if (cl.hasOption('f')) {
             String filename = cl.getOptionValue('f');
             try {
@@ -208,6 +231,7 @@ public class App {
             }
         }
 
+        //The URL to rip.
         if (cl.hasOption('u')) {
             String url = cl.getOptionValue('u').trim();
             ripURL(url, cl.hasOption("n"));

src/main/java/com/rarchives/ripme/utils/Utils.java

@@ -89,6 +89,12 @@ public class Utils {
         return workingDir;
     }
 
+    /**
+     * Gets the value of a specific config key.
+     * 
+     * @param key The name of the config parameter you want to find.
+     * @param defaultValue What the default value would be.
+     */
     public static String getConfigString(String key, String defaultValue) {
         return config.getString(key, defaultValue);
     }
@@ -142,31 +148,53 @@ public class Utils {
         }
     }
 
+    /**
+     * Determines if your current system is a Windows system.
+     */
     private static boolean isWindows() {
         return OS.contains("win");
     }
 
+    /**
+     * Determines if your current system is a Mac system
+     */
     private static boolean isMacOS() {
         return OS.contains("mac");
     }
 
+    /**
+     * Determines if current system is based on UNIX
+     */
     private static boolean isUnix() {
         return OS.contains("nix") || OS.contains("nux") || OS.contains("bsd");
     }
 
+    /**
+     * Gets the directory of where the config file is stored on a Windows machine.
+     */
     private static String getWindowsConfigDir() {
         return System.getenv("LOCALAPPDATA") + File.separator + "ripme";
     }
 
+    
+    /**
+     * Gets the directory of where the config file is stored on a UNIX machine.
+     */
     private static String getUnixConfigDir() {
         return System.getProperty("user.home") + File.separator + ".config" + File.separator + "ripme";
     }
     
+    /**
+     * Gets the directory of where the config file is stored on a Mac machine.
+     */
     private static String getMacOSConfigDir() {
         return System.getProperty("user.home")
                 + File.separator + "Library" + File.separator + "Application Support" + File.separator + "ripme";
     }
 
+    /**
+     * Determines if the app is running in a portable mode. i.e. on a USB stick
+     */
     private static boolean portableMode() {
         try {
             File f = new File(new File(".").getCanonicalPath() + File.separator + configFile);
@@ -179,7 +207,9 @@ public class Utils {
         return false;
     }
 
-
+    /**
+     * Gets the directory of the config directory, for all systems.
+     */
     public static String getConfigDir() {
         if (portableMode()) {
             try {
@@ -199,17 +229,24 @@ public class Utils {
             return ".";
         }
     }
-    // Delete the url history file
+    /**
+     * Delete the url history file
+     */
     public static void clearURLHistory() {
         File file = new File(getURLHistoryFile());
         file.delete();
     }
 
-    // Return the path of the url history file
+    /**
+     *  Return the path of the url history file
+     */
     public static String getURLHistoryFile() {
         return getConfigDir() + File.separator + "url_history.txt";
     }
 
+    /**
+     * Gets the path to the configuration file.
+     */
     private static String getConfigFilePath() {
         return getConfigDir() + File.separator + configFile;
     }
@@ -235,6 +272,15 @@ public class Utils {
         return prettySaveAs;
     }
 
+    /**
+     * Strips away URL parameters, which usually appear at the end of URLs.
+     * E.g. the ?query on PHP
+     * 
+     * @param url The URL to filter/strip
+     * @param parameter The parameter to strip
+     * 
+     * @return The stripped URL
+     */
     public static String stripURLParameter(String url, String parameter) {
         int paramIndex = url.indexOf("?" + parameter);
         boolean wasFirstParam = true;
@@ -262,6 +308,7 @@ public class Utils {
     /**
      * Removes the current working directory from a given filename
      * @param file
+     *      Path to the file
      * @return
      *      'file' without the leading current working directory
      */
@@ -345,9 +392,24 @@ public class Utils {
     }
 
     private static final int SHORTENED_PATH_LENGTH = 12;
+    /**
+     * Shortens the path to a file
+     * @param path
+     *      String of the path to the file
+     * @return
+     *      The simplified path to the file.
+     */
     public static String shortenPath(String path) {
         return shortenPath(new File(path));
     }
+
+    /**
+     * Shortens the path to a file
+     * @param file
+     *      File object that you want the shortened path of.
+     * @return 
+     *      The simplified path to the file.
+     */
     public static String shortenPath(File file) {
         String path = removeCWD(file);
         if (path.length() < SHORTENED_PATH_LENGTH * 2) {
@@ -358,6 +420,13 @@ public class Utils {
                 + path.substring(path.length() - SHORTENED_PATH_LENGTH);
     }
 
+    /**
+     * Sanitizes a string so that a filesystem can handle it
+     * @param text
+     *      The text to be sanitized.
+     * @return
+     *      The sanitized text.
+     */
     public static String filesystemSanitized(String text) {
         text = text.replaceAll("[^a-zA-Z0-9.-]", "_");
         return text;
@@ -407,6 +476,13 @@ public class Utils {
         return original;
     }
 
+    /**
+     * Converts an integer into a human readable string
+     * @param bytes
+     *      Non-human readable integer.
+     * @return
+     *      Human readable interpretation of a byte.
+     */
     public static String bytesToHumanReadable(int bytes) {
         float fbytes = (float) bytes;
         String[] mags = new String[] {"", "K", "M", "G", "T"};
@@ -418,6 +494,10 @@ public class Utils {
         return String.format("%.2f%siB", fbytes, mags[magIndex]);
     }
 
+    /**
+     * Gets and returns a list of all the album rippers present in the "com.rarchives.ripme.ripper.rippers" package.
+     * @return List<String> of all album rippers present.
+     */
     public static List<String> getListOfAlbumRippers() throws Exception {
         List<String> list = new ArrayList<>();
         for (Constructor<?> ripper : AbstractRipper.getRipperConstructors("com.rarchives.ripme.ripper.rippers")) {
@@ -425,6 +505,11 @@ public class Utils {
         }
         return list;
     }
+
+    /**
+     * Gets and returns a list of all video rippers present in the "com.rarchives.rime.rippers.video" package
+     * @return List<String> of all the video rippers.
+     */
     public static List<String> getListOfVideoRippers() throws Exception {
         List<String> list = new ArrayList<>();
         for (Constructor<?> ripper : AbstractRipper.getRipperConstructors("com.rarchives.ripme.ripper.rippers.video")) {
@@ -433,6 +518,11 @@ public class Utils {
         return list;
     }
 
+    /**
+     * Plays a sound from a file.
+     * @param filename 
+     *      Path to the sound file
+     */
     public static void playSound(String filename) {
         URL resource = ClassLoader.getSystemClassLoader().getResource(filename);
         try {
@@ -570,6 +660,9 @@ public class Utils {
         cookieCache = new HashMap<String, HashMap<String, String>>();
     }
 
+    /**
+     * Gets all the cookies from a certain host
+     */
     public static Map<String, String> getCookies(String host) {
         HashMap<String, String> domainCookies = cookieCache.get(host);
         if (domainCookies == null) {
@@ -587,6 +680,12 @@ public class Utils {
         return domainCookies;
     }
 
+    /**
+     * Gets the ResourceBundle AKA language package.
+     * Used for choosing the language of the UI.
+     * 
+     * @return Returns the default resource bundle using the language specified in the config file.
+     */
     public static ResourceBundle getResourceBundle() {
         if (!getConfigString("lang", "").equals("")) {
             String[] langCode = getConfigString("lang", "").split("_");