#3 Support for Source Maps

- add documentation

Author: agabrys

README.md

@@ -32,20 +32,37 @@ The idea for the `NativeLessCompiler` class was based on the [lesscss-java](http
 library by [Marcel Overdijk](https://github.com/marceloverdijk).
 
 # Usage
-How to compile a source file:
+The `LessCompiler` contains 14 methods. Below is an example of how to use some of them:
 ```
+String cssCode = null;
+LessOptions options = null;
+
 // create compiler
 LessCompiler compiler = new LessCompiler();
 
 // compile source code
-String cssCode1 = compiler.compile(".basic { display: block; }");
+cssCode = compiler.compile(".basic { display: block; }");
+
+// compile source code with custom options
+options = new LessOptionsBuilder().ieCompatibilityOff().build();
+cssCode = compiler.compile(".basic { display: block; }", options);
 
 // compile source file
-String cssCode2 = compiler.compile(new File("/source.less"));
+cssCode = compiler.compile(new File("source.less"));
 
 // compile source file and save CSS code in an output file
-compiler.compile(new File("/source.less"), new File("/output.css"));
+compiler.compile(new File("source.less"), new File("output.css"));
 
 // compile source file and compress CSS code
-String compressedCssCode = compiler.compileAndCompress(new File("/source.less"));
+cssCode = compiler.compileAndCompress(new File("source.less"));
+
+// compile source code and generate inline source map
+cssCode = compiler.compileWithInlineSourceMap(".basic { display: block; }", new LessOptions());
+
+// compile source file and generate source map (save it in output.map file)
+options = new LessOptionsBuilder().sourceMapBasePath("basePath").build();
+compiler.compileWithSourceMap(new File("source.less"), new File("output.css"), new File("output.map"), options);
+
+// compile source file and generate source map (save it in output.css.map file)
+compiler.compileWithSourceMap(new File("source.less"), new File("output.css"), options);
 ```

src/main/java/biz/gabrys/lesscss/compiler2/LessCompiler.java

@@ -25,27 +25,73 @@
  * <a href="https://github.com/less/less.js/releases/tag/v1.7.5">Less 1.7.5</a>.
  * </p>
  * <p>
- * How to use:
+ * This class is a facade for the {@link NativeLessCompiler}. List of methods with a developer-friendly API:
+ * </p>
+ * <ul>
+ * <li>{@link #compile(CharSequence)} - compiles a Less source code to a CSS code</li>
+ * <li>{@link #compile(CharSequence, LessOptions)} - compiles a Less source code with custom configuration options to a
+ * CSS code</li>
+ * <li>{@link #compile(File)} - compiles a Less source file to a CSS code</li>
+ * <li>{@link #compile(File, LessOptions)} - compiles a Less source file with custom configuration options to a CSS
+ * code</li>
+ * <li>{@link #compile(File, File)} - compiles a Less source file to a CSS code and saves it in an output file</li>
+ * <li>{@link #compile(File, File, LessOptions)} - compiles a Less source file with custom configuration options and
+ * saves result in an output file</li>
+ * <li>{@link #compileAndCompress(CharSequence)} - compiles a Less source file to a compressed CSS code</li>
+ * <li>{@link #compileAndCompress(File)} - compiles a Less source file to a compressed CSS code</li>
+ * <li>{@link #compileAndCompress(File, File)} - compiles a Less source file to a compressed CSS code and saves it in an
+ * output file</li>
+ * <li>{@link #compileWithInlineSourceMap(CharSequence, LessOptions)} - compiles a Less source code with custom
+ * configuration options to a CSS code with an inline Source Map</li>
+ * <li>{@link #compileWithInlineSourceMap(File, File, LessOptions)} - compiles a Less source file with custom
+ * configuration to a CSS code with an inline Source Map and saves it in an output file</li>
+ * <li>{@link #compileWithInlineSourceMap(File, LessOptions)} - compiles a Less source file with custom configuration
+ * options to a CSS code with an inline Source Map</li>
+ * <li>{@link #compileWithSourceMap(File, File, LessOptions)} - compiles a Less source file with custom configuration to
+ * a CSS code with a Source Map (Source Map file name is equal to the output file name with {@code map} extension)</li>
+ * <li>{@link #compileWithSourceMap(File, File, File, LessOptions)} - compiles a Less source file with custom
+ * configuration to a CSS code with a Source Map</li>
+ * </ul>
+ * <p>
+ * Example code:
  * </p>
  * 
  * <pre>
+ * String cssCode = null;
+ * {@link LessOptions} options = null;
+ * 
  * // create compiler
- * LessCompiler compiler = new LessCompiler();
- *
+ * LessCompiler compiler = new {@link #LessCompiler() LessCompiler}();
+ * 
  * // compile source code
- * String cssCode1 = compiler.compile(".basic { display: block; }");
+ * cssCode = compiler.{@link #compile(CharSequence) compile}(".basic { display: block; }");
+ * 
+ * // compile source code with custom options
+ * options = new {@link LessOptionsBuilder#LessOptionsBuilder() LessOptionsBuilder}().{@link LessOptionsBuilder#ieCompatibilityOff() ieCompatibilityOff}().{@link LessOptionsBuilder#build() build}();
+ * cssCode = compiler.{@link #compile(CharSequence, LessOptions) compile}(".basic { display: block; }", options);
  * 
  * // compile source file
- * String cssCode2 = compiler.compile(new File("/source.less"));
+ * cssCode = compiler.{@link #compile(File) compile}(new File("source.less"));
  * 
  * // compile source file and save CSS code in an output file
- * compiler.compile(new File("/source.less"), new File("/output.css"));
+ * compiler.{@link #compile(File, File) compile}(new File("source.less"), new File("output.css"));
  * 
  * // compile source file and compress CSS code
- * String compressedCssCode = compiler.compileAndCompress(new File("/source.less"));
+ * cssCode = compiler.{@link #compileAndCompress(File) compileAndCompress}(new File("source.less"));
+ * 
+ * // compile source code and generate inline source map
+ * cssCode = compiler.{@link #compileWithInlineSourceMap(CharSequence, LessOptions) compileWithInlineSourceMap}(".basic { display: block; }", new {@link LessOptions#LessOptions() LessOptions}());
+ * 
+ * // compile source file and generate source map (save it in output.map file)
+ * options = new {@link LessOptionsBuilder#LessOptionsBuilder() LessOptionsBuilder}().{@link LessOptionsBuilder#sourceMapBasePath(CharSequence) sourceMapBasePath}("basePath").{@link LessOptionsBuilder#build() build}();
+ * compiler.{@link #compileWithSourceMap(File, File, File, LessOptions) compileWithSourceMap}(new File("source.less"), new File("output.css"), new File("output.map"), options);
+ * 
+ * // compile source file and generate source map (save it in output.css.map file)
+ * compiler.{@link #compileWithSourceMap(File, File, LessOptions) compileWithSourceMap}(new File("source.less"), new File("output.css"), options);
  * </pre>
  * 
  * @since 2.0.0
+ * @see LessOptionsBuilder
  */
 public class LessCompiler {
 
@@ -365,7 +411,8 @@ public void compileWithInlineSourceMap(final File source, final File output, fin
 
     /**
      * Compiles a Less source file with custom configuration to a CSS code with a Source Map. The CSS code will be saved
-     * in an output file and the Source Map in a file with name equal to the output file name with map extension.
+     * in an output file and the Source Map in a file with name equal to the output file name with {@code map}
+     * extension.
      * @param source the source file (cannot be {@code null} and must exist).
      * @param output the output file (cannot be {@code null}).
      * @param options the configuration options (can be {@code null}).

src/main/java/biz/gabrys/lesscss/compiler2/LessOptions.java

@@ -17,8 +17,47 @@
 import java.util.List;
 
 /**
+ * <p>
  * Represents <a href="http://lesscss.org/usage/index.html#command-line-usage-options">Less compiler options</a>
  * responsible for controlling the {@link LessCompiler} compilation process.
+ * </p>
+ * <p>
+ * Base options:
+ * </p>
+ * <ul>
+ * <li>{@link #isCompress() compress} - whether a CSS code should be compressed (default: {@code false})</li>
+ * <li>{@link #isIeCompatibility() IE compatibility} - whether a CSS code should be compatible with Internet Explorer
+ * browser (default: {@code true})</li>
+ * <li>{@link #getIncludePaths() included paths} - available include paths (default: {@code empty collection})</li>
+ * <li>{@link #isJavaScript() JavaScript} - whether a compiler should allow usage of JavaScript language (default:
+ * {@code true})</li>
+ * <li>{@link #getLineNumbers() line numbers} - whether a compiler should generate inline source-mapping (default:
+ * {@link LineNumbersValue#OFF})</li>
+ * <li>{@link #isRelativeUrls() relative URLs} - whether a compiler should rewrite relative URLs (default:
+ * {@code false})</li>
+ * <li>{@link #getRootPath() root path} - a path which will be added to every generated import and URL in CSS code
+ * (default: {@code null})</li>
+ * <li>{@link #isSilent() silent} - whether a compiler shouldn't log compilation warnings (default: {@code false})</li>
+ * <li>{@link #isStrictImports() strict imports} - whether a compiler should disallow an @import operation inside of
+ * either @media blocks or other selector blocks (default: {@code false})</li>
+ * <li>{@link #isStrictMath() strict math} - whether a compiler should try and process all maths in Less code (default:
+ * {@code false})</li>
+ * <li>{@link #isStrictUnits() strict units} - whether a compiler should guess units in Less code when it does maths
+ * (default: {@code false})</li>
+ * </ul>
+ * <p>
+ * Source Map options:
+ * </p>
+ * <ul>
+ * <li>{@link #getSourceMapBasePath() base path} - a path that will be removed from each of the Less file paths inside
+ * the Source Map and also from the path to the map file specified in your output CSS (default: {@code null})</li>
+ * <li>{@link #isSourceMapLessInline() Less inline} - whether a compiler should include all of the Less files in to the
+ * Source Map (default: {@code false})</li>
+ * <li>{@link #getSourceMapRootPath() root path} - a path that will be prepended to each of the Less file paths inside
+ * the Source Map and also to the path to the map file specified in your output CSS (default: {@code null})</li>
+ * <li>{@link #getSourceMapUrl() URL} - a path which will overwrite the URL in the CSS that points at the Source Map
+ * file (default: {@code null})</li>
+ * </ul>
  * @since 2.0.0
  * @see LessOptionsBuilder
  */
@@ -139,20 +178,21 @@ public void setCompress(final boolean compress) {
     }
 
     /**
-     * Sets whether a CSS code should be compatible with IE browser (default: {@code true}). Used for the
+     * Sets whether a CSS code should be compatible with Internet Explorer browser (default: {@code true}). Used for the
      * {@code data-uri} function to ensure that images aren't created that are too large for the browser to handle.
-     * @return {@code true} whether the CSS code should be compatible with IE browser, otherwise {@code false}.
+     * @return {@code true} whether the CSS code should be compatible with Internet Explorer browser, otherwise
+     *         {@code false}.
      * @since 2.0.0
      */
     public boolean isIeCompatibility() {
         return ieCompatibility;
     }
 
     /**
-     * Sets whether a CSS code should be compatible with IE browser (default: {@code true}). Used for the
+     * Sets whether a CSS code should be compatible with Internet Explorer browser (default: {@code true}). Used for the
      * {@code data-uri} function to ensure that images aren't created that are too large for the browser to handle.
-     * @param ieCompatibility {@code true} whether the CSS code should be compatible with IE browser, otherwise
-     *            {@code false}.
+     * @param ieCompatibility {@code true} whether the CSS code should be compatible with Internet Explorer browser,
+     *            otherwise {@code false}.
      * @since 2.0.0
      */
     public void setIeCompatibility(final boolean ieCompatibility) {
@@ -607,7 +647,7 @@ public void setSourceMapLessInline(final boolean sourceMapLessInline) {
     }
 
     /**
-     * Returns a path which will overwrite the URL in the CSS that points at the Source Map map file (default:
+     * Returns a path which will overwrite the URL in the CSS that points at the Source Map file (default:
      * {@code null}). This is for cases when the {@link #getSourceMapRootPath() root path} and the
      * {@link #getSourceMapBasePath() base path} options are not producing exactly what you need.
      * @return the Source Map URL.
@@ -620,8 +660,8 @@ public String getSourceMapUrl() {
     }
 
     /**
-     * Sets a path which will overwrite the URL in the CSS that points at the Source Map map file (default:
-     * {@code null}). This is for cases when the {@link #setSourceMapRootPath(String) root path} and the
+     * Sets a path which will overwrite the URL in the CSS that points at the Source Map file (default: {@code null}).
+     * This is for cases when the {@link #setSourceMapRootPath(String) root path} and the
      * {@link #setSourceMapBasePath(String) base path} options are not producing exactly what you need.
      * @param sourceMapUrl the Source Map URL.
      * @since 2.0.0

src/main/java/biz/gabrys/lesscss/compiler2/LessOptionsBuilder.java

@@ -20,7 +20,27 @@
 import biz.gabrys.lesscss.compiler2.util.StringUtils;
 
 /**
+ * <p>
  * Responsible for creating new instances of the {@link LessOptions}.
+ * </p>
+ * <p>
+ * Example code:
+ * </p>
+ * 
+ * <pre>
+ * {@link LessOptions} options = null;
+ * 
+ * // create options with enabled code compression
+ * options = new {@link #LessOptionsBuilder() LessOptionsBuilder}().{@link #compressOn() compressOn}().{@link #build() build}();
+ * 
+ * // create options with enabled strict units and disabled IE compatibility
+ * options = new {@link #LessOptionsBuilder() LessOptionsBuilder}().{@link #strictUnitsOn() strictUnitsOn}().{@link #ieCompatibilityOff() ieCompatibilityOff}().{@link #build() build}();
+ * 
+ * // use existing options object to create a new one
+ * boolean compression = false;
+ * options =  new {@link #LessOptionsBuilder(LessOptions) LessOptionsBuilder}(options).{@link #compress(boolean) compress}(compression).{@link #build() build}();
+ * </pre>
+ * 
  * @since 2.0.0
  */
 public class LessOptionsBuilder {

src/main/java/biz/gabrys/lesscss/compiler2/NativeLessCompiler.java

@@ -49,23 +49,24 @@
  * <a href="https://github.com/marceloverdijk">Marcel Overdijk</a>.
  * </p>
  * <p>
- * How to use:
+ * Example code:
  * </p>
  * 
  * <pre>
  * // create compiler and source file
- * NativeLessCompiler compiler = new NativeLessCompiler();
+ * NativeLessCompiler compiler = new {@link #NativeLessCompiler() NativeLessCompiler}();
  * File input = new File("/less/file.less");
  * 
  * // compile source file
- * String cssCode = compiler.execute(new NativeLessOptionsBuilder().inputFile(input).create());
+ * String cssCode = compiler.{@link #execute(Collection) execute}(new {@link NativeLessOptionsBuilder#NativeLessOptionsBuilder() NativeLessOptionsBuilder}().inputFile(input).build());
  * 
- * // compile source file and compress CSS code
- * Collection&lt;Object&gt; options = new NativeLessOptionsBuilder().inputFile(input).compress(true).create();
- * String cssCompressedCode = compiler.execute(options);
+ * // compile source file with enabled CSS code compression
+ * Collection&lt;Object&gt; options = new {@link NativeLessOptionsBuilder#NativeLessOptionsBuilder() NativeLessOptionsBuilder}().inputFile(input).compress(true).build();
+ * String cssCompressedCode = compiler.{@link #execute(Collection) execute}(options);
  * </pre>
  * 
  * @since 2.0.0
+ * @see NativeLessOptionsBuilder
  */
 public class NativeLessCompiler {
 
@@ -93,9 +94,10 @@ public NativeLessCompiler() {
 
     /**
      * Executes the compiler. You can use standard
-     * <a href="http://lesscss.org/usage/index.html#command-line-usage-options">Less options</a> with some exceptions:
+     * <a href="http://lesscss.org/usage/index.html#command-line-usage-options">Less command line options</a> with some
+     * exceptions:
      * <ul>
-     * <li>use {@link #INCLUDE_PATHS_SEPARATOR} to separate paths in {@code --include-path"} option instead of ';'
+     * <li>use {@link #INCLUDE_PATHS_SEPARATOR} to separate paths in {@code --include-path} option instead of ';'
      * character on Windows and ':' character on Unix/Linux machines</li>
      * <li>does not support options:
      * <ul>