com.jme3.asset.plugins: javadoc additions

jme3-core/src/plugins/java/com/jme3/asset/plugins/ClasspathLocator.java

@@ -41,6 +41,16 @@ import java.util.logging.Logger;
 
 /**
  * The <code>ClasspathLocator</code> looks up an asset in the classpath.
+ * 
+ * This locator is used by default in all jME3 projects (unless 
+ * {@link AssetManager#unregisterLocator(java.lang.String, java.lang.Class) unregistered}
+ * ).
+ * Unlike Java's default resource loading mechanism, the <code>ClasspathLocator</code>
+ * enforces case-sensitivity on platforms which do not have it such as Windows.
+ * Therefore, it is critical to provide a path matching the case of the file on
+ * the filesystem. This also ensures that the file can be loaded if it was
+ * later included in a <code>.JAR</code> file instead of a folder.
+ * 
  * @author Kirill Vainer
  */
 public class ClasspathLocator implements AssetLocator {

jme3-core/src/plugins/java/com/jme3/asset/plugins/FileLocator.java

@@ -37,6 +37,7 @@ import java.io.*;
 /**
  * <code>FileLocator</code> allows you to specify a folder where to
  * look for assets. 
+ * 
  * @author Kirill Vainer
  */
 public class FileLocator implements AssetLocator {

jme3-core/src/plugins/java/com/jme3/asset/plugins/HttpZipLocator.java

@@ -52,6 +52,23 @@ import java.util.zip.Inflater;
 import java.util.zip.InflaterInputStream;
 import java.util.zip.ZipEntry;
 
+/**
+ * <code>HttpZipLocator</code> is similar to {@link ZipLocator}, except
+ * it allows loading assets from a <code>.ZIP</code> file on the web instead of
+ * on the local filesystem.
+ * <p>
+ * The root path must be a valid HTTP(S) {@link URL} pointing to ZIP or
+ * ZIP-like file (such as a JAR). For example,<br>
+ * <code>https://www.example.com/my/sub/path/assets.zip</code>.
+ * <p>
+ * The locator is designed in such a way that it does not require downloading
+ * the entire <code>.ZIP</code> file from the web in order to load
+ * assets from it. Instead, the ZIP header is extracted first, and then
+ * is used to lookup assets from within the ZIP file and download them
+ * as requested by the user. 
+ * 
+ * @author Kirill Vainer
+ */
 public class HttpZipLocator implements AssetLocator {
 
     private static final Logger logger = Logger.getLogger(HttpZipLocator.class.getName());

jme3-core/src/plugins/java/com/jme3/asset/plugins/UrlLocator.java

@@ -46,6 +46,10 @@ import java.util.logging.Logger;
  * <code>UrlLocator</code> is a locator that combines a root URL
  * and the given path in the AssetKey to construct a new URL
  * that allows locating the asset.
+ * <p>
+ * The root path must be a valid {@link URL}, for example, <br>
+ * <code>https://www.example.com/assets/</code>
+ * 
  * @author Kirill Vainer
  */
 public class UrlLocator implements AssetLocator {

jme3-core/src/plugins/java/com/jme3/asset/plugins/ZipLocator.java

@@ -40,7 +40,13 @@ import java.util.zip.ZipEntry;
 import java.util.zip.ZipFile;
 
 /**
- * <code>ZipLocator</code> is a locator that looks up resources in a .ZIP file.
+ * <code>ZipLocator</code> is a locator that looks up resources in a 
+ * <code>.ZIP</code> file.
+ * 
+ * The root path must be a valid ZIP or ZIP-like {@link File file}, 
+ * for example, <br>
+ * <code>C:\My App\data.zip</code>
+ * 
  * @author Kirill Vainer
  */
 public class ZipLocator implements AssetLocator {