Better documentations

Author: sapher

README.md

@@ -1,77 +1,34 @@
 # youtubedl-java [![Build Status](https://travis-ci.org/sapher/youtubedl-java.svg?branch=master)](https://travis-ci.org/sapher/youtubedl-java)
 
-
-Just a simple WIP java wrapper for youtubedl
-
-#Table of contents
-
-- [Prerequisite](#prerequisite)
-- [Usage](#usage)
-- [Links](#links)
+A simple java wrapper for [youtube-dl](https://github.com/rg3/youtube-dl) executable
 
 # Prerequisite
-You need `youtube-dl` to be installed and available. You can follow [those instructions](https://github.com/rg3/youtube-dl/blob/master/README.md#installation) to install `youtube-dl`
-
-# Usage
-
-YoutubeDL wrapper is compose of 3 main class : `YoutubeDL`, `YoutubeDLRequest`, `YoutubeDLResponse`.
-
-## YoutubeDL
-Static class that execute a request and return a response.
-
-### Execute a command
-
-```
-YoutubeDL.execute('--version');
-```
-
-### Execute a request
 
-```
-YoutubeDLRequest request = new YoutubeDLRequest();
-YoutubeDL.execute(request);
-```
-
-## YoutubeDLRequest
-Represent a command for youtube-dl to execute.
-You can **set** and **get** all options handle by youtube-dl : [YoutubeDL Options](https://github.com/rg3/youtube-dl/blob/master/README.md#options).
-Don't use those deprecated (you can but.. don't).
+Youtube-dl should be installed and available.
 
-```
-// Example to set / get rate limit
-request.setRateLimit(1024);
-request.getRateLimit();
-```
+# Usage
 
-## YoutubeDLResponse
-Represent the result of a request.
 
-This object is composed of:
+## Make request
 
-* **exitCode** Exit code of youtube-dl programm
-*  **err** String from stderr
-*  **out** String from stdout
-*  **directory** Directory where the programme has been launched
-* *more useful to come...*
+```java
+// Video url to download
+String videoUrl = "https://www.youtube.com/watch?v=dQw4w9WgXcQ";
 
-## Custom request
+// Destination directory
+String directory = System.getProperty("user.home");
 
-You can use `YoutubeDLRequest` object to build any  command you want.
+// Build request
+YoutubeDLRequest request = new YoutubeDLRequest(videoUrl, directory);
+request.setOption("ignore-errors");		// --ignore-errors
+request.setOption("output", "%(id)s");	// --output "%(id)s"
+request.setOption("retries", 10);		// --retries 10
 
-```java
-// Download a video
-YoutubeDLRequest request = new YoutubeDLRequest();
-request.setUrl("https://www.youtube.com/watch?v=dQw4w9WgXcQ");
-request.setDirectory("/Users/johndoe/Desktop");
+// Make request and return response
 YoutubeDLResponse response = YoutubeDL.execute(request);
 
-// will result to youtube-dl https://www.youtube.com/watch?v=dQw4w9WgXcQ
+// Response
+String stdOut = response.getOut(); // Executable output
 ```
-
-Be care, you can build a nonsensical command.
-
 # Links
-
-[YoutubeDL Documentation](https://github.com/rg3/youtube-dl/blob/master/README.md#installation)
-
-**[Back to top](#table-of-contents)**
+* [Youtube-dl documentation](https://github.com/sapher/youtubedl-java)

src/main/java/com/sapher/youtubedl/YoutubeDL.java

@@ -12,24 +12,32 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * <p>Provide an interface for youtube-dl executable</p>
+ *
+ * <p>
+ *     For more information on youtube-dl, please see
+ *     <a href="https://github.com/rg3/youtube-dl/blob/master/README.md">YoutubeDL Documentation</a>
+ * </p>
+ */
 public class YoutubeDL {
 
     /**
      * Youtube-dl executable name
      */
-    public static final String executableName = "youtube-dl";
+    protected static final String executableName = "youtube-dl";
 
     /**
      * Append executable name to command
      * @param command Command string
      * @return Command string
      */
-    private static String buildCommand(String command) {
+    protected static String buildCommand(String command) {
         return String.format("%s %s", executableName, command);
     }
 
     /**
-     * Execute youtube-dl command
+     * Execute youtube-dl request
      * @param request request object
      * @return response object
      * @throws YoutubeDLException
@@ -113,7 +121,7 @@ public static VideoInfo getVideoInfo(String url) throws YoutubeDLException  {
         // Build request
         YoutubeDLRequest request = new YoutubeDLRequest(url);
         request.setOption("dump-json");
-        //request.setOption("no-playlist");
+        request.setOption("no-playlist");
         YoutubeDLResponse response = YoutubeDL.execute(request);
 
         // Parse result
@@ -172,31 +180,4 @@ public static List<String> getTags(String url) throws YoutubeDLException {
         VideoInfo info = getVideoInfo(url);
         return info.tags;
     }
-
-    /**public static List<VideoSubtitle> getSubtitles(String url) throws YoutubeDLException {
-        VideoInfo info = getVideoInfo(url);
-        return info.subtitles;
-    }**/
-
-    /**
-     * Download audio of a video
-     * @param url Video Url
-     * @param dir Destination directory
-     * @param format Audio format
-     * @param quality Audio quality
-     * @param output Output filename template
-     * @throws YoutubeDLException
-     */
-    public static YoutubeDLResponse downloadAudio(String url, String dir, String format, int quality, String output) throws YoutubeDLException {
-
-        YoutubeDLRequest request = new YoutubeDLRequest(url, dir);
-        //request.setDirectory(dir);
-        request.setOption("no-playlist");
-        //request.setOption("extract-audio");
-        request.setOption("format", format);
-        request.setOption("audio-quality", quality);
-        request.setOption("output", output);
-
-        return YoutubeDL.execute(request);
-    }
 }

src/main/java/com/sapher/youtubedl/YoutubeDLException.java

@@ -1,17 +1,35 @@
 package com.sapher.youtubedl;
 
+/**
+ * YoutubeDL Exception
+ */
 public class YoutubeDLException extends Exception {
 
+    /**
+     * Exception message
+     */
     private String message;
 
+    /**
+     * Construct YoutubeDLException with a message
+     * @param message
+     */
     public YoutubeDLException(String message) {
         this.message = message;
     }
 
+    /**
+     * Construct YoutubeDLException from another exception
+     * @param e Any exception
+     */
     public YoutubeDLException(Exception e) {
         message = e.getMessage();
     }
 
+    /**
+     * Get exception message
+     * @return exception message
+     */
     @Override
     public String getMessage() {
         return message;

src/main/java/com/sapher/youtubedl/YoutubeDLRequest.java

@@ -2,11 +2,24 @@
 
 import java.util.*;
 
+/**
+ * YoutubeDL request
+ */
 public class YoutubeDLRequest {
 
+    /**
+     * Executable working directory
+     */
     private String directory;
+
+    /**
+     * Video Url
+     */
     private String url;
 
+    /**
+     * List of executable options
+     */
     private Map<String, String> options = new HashMap<String, String>();
 
     public String getDirectory() {
@@ -41,19 +54,35 @@ public void setOption(String key, int value) {
         options.put(key, String.valueOf(value));
     }
 
+    /**
+     * Constructor
+     */
     public YoutubeDLRequest() {
 
     }
 
+    /**
+     * Construct a request with a videoUrl
+     * @param url
+     */
     public YoutubeDLRequest(String url) {
         this.url = url;
     }
 
+    /**
+     * Construct a request with a videoUrl and working directory
+     * @param url
+     * @param directory
+     */
     public YoutubeDLRequest(String url, String directory) {
         this.url = url;
         this.directory = directory;
     }
 
+    /**
+     * Transform options to a string that the executable will execute
+     * @return Command string
+     */
     protected String buildOptions() {
 
         StringBuilder builder = new StringBuilder();

src/main/java/com/sapher/youtubedl/YoutubeDLResponse.java

@@ -1,8 +1,10 @@
 package com.sapher.youtubedl;
 
-
 import java.util.Map;
 
+/**
+ * YoutubeDL response
+ */
 public class YoutubeDLResponse {
 
     private Map<String, String> options;

src/test/java/com/sapher/youtubedl/YoutubeDLTest.java

@@ -10,8 +10,8 @@
 
 public class YoutubeDLTest {
 
-    private final String directory = System.getProperty("user.home");
-    //private final String directory = System.getProperty("java.io.tmpdir");
+    //private final String directory = System.getProperty("user.home");
+    private final String directory = System.getProperty("java.io.tmpdir");
     private final String videoUrl = "https://www.youtube.com/watch?v=dQw4w9WgXcQ";
 
     @Test
@@ -90,16 +90,4 @@ public void testGetCategories() throws YoutubeDLException {
         Assert.assertNotNull(categories);
         Assert.assertTrue(categories.size() > 0);
     }
-
-    /**@Test
-    public void testDownloadAudio() throws YoutubeDLException {
-        YoutubeDLResponse response = YoutubeDL.downloadAudio(videoUrl, directory, "17", 0, "%(id)s");
-    }**/
-
-    /**@Test
-    public void testGetSubtitles() throws YoutubeDLException {
-        List<VideoSubtitle> subtitles = YoutubeDL.getSubtitles(videoUrl);
-        Assert.assertNotNull(subtitles);
-        Assert.assertTrue(subtitles.size() > 0);
-    }**/
 }