Format + Documentation + Minor improvements

core/build.gradle

@@ -6,9 +6,9 @@ apply plugin: 'java'
 sourceCompatibility = 1.8
 
 repositories {
-    mavenCentral()
+	mavenCentral()
 }
 
 dependencies {
-    testCompile group: 'junit', name: 'junit', version: '4.11'
+	testCompile group: 'junit', name: 'junit', version: '4.11'
 }

core/src/main/java/com/electronwill/nightconfig/core/StringUtils.java

@@ -10,7 +10,7 @@
  */
 public final class StringUtils {
 
-	private StringUtils() {}
+	private StringUtils() {}//Utility class can't be constructed
 
 	/**
 	 * Splits a String around each occurence of the specified character. The result is <b>not</b> the same as

core/src/main/java/com/electronwill/nightconfig/core/serialization/CharacterInput.java

@@ -1,11 +1,32 @@
 package com.electronwill.nightconfig.core.serialization;
 
 /**
+ * Interface for sources of characters.
+ * <p>
+ * The readXXX() and seek() methods do not throw any exception when the end of the available data
+ * is reached, but return special values.
+ * <p>
+ * The readCharXXX() and seekChar() methods do throw a RuntimeException when the end of the available
+ * data is reached.
+ * </p>
+ *
  * @author TheElectronWill
  */
 public interface CharacterInput {
+	/**
+	 * Reads the next character.
+	 *
+	 * @return the next char, or -1 if there is no more available data
+	 */
 	int read();
 
+	/**
+	 * Reads the next characters, skipping some characters. Returns the next character that is not in the
+	 * given array.
+	 *
+	 * @param toSkip the characters to skip
+	 * @return the next character that is not in {@code toSkip}, or -1 if there is no more available data
+	 */
 	default int readAndSkip(char[] toSkip) {
 		int c;
 		do {
@@ -14,10 +35,38 @@ default int readAndSkip(char[] toSkip) {
 		return c;
 	}
 
+	/**
+	 * Reads the next n characters. If there isn't n available characters, this method returns -1.
+	 *
+	 * @param n the number of characters to read
+	 * @return an array containing the next n characters, or null if there is no more available data
+	 */
 	char[] read(int n);
 
+	/**
+	 * Returns the next character, without moving the reading position forward. After a call to
+	 * {@code seek()}, the method {@link #read()} will return the exact same character.
+	 *
+	 * @return the next character, or -1 if there is no more available data
+	 */
+	int seek();
+
+	/**
+	 * Reads the next character, throwing an exception if there is no more available data.
+	 *
+	 * @return the next character
+	 * @throws ParsingException if there is no more available data
+	 */
 	char readChar();
 
+	/**
+	 * Reads the next characters, skipping some characters. Returns the next character that is not in the
+	 * given array. This method throws an exception if there is no more available data.
+	 *
+	 * @param toSkip the characters to skip
+	 * @return the next character that is not in {@code toSkip}, or -1 if there is no more available data
+	 * @throws ParsingException if there is no more available data
+	 */
 	default char readCharAndSkip(char[] toSkip) {
 		char c;
 		do {
@@ -26,7 +75,32 @@ default char readCharAndSkip(char[] toSkip) {
 		return c;
 	}
 
+	/**
+	 * Reads the next n characters. If there isn't n available characters, this method throws an exception.
+	 *
+	 * @param n the number of characters to read
+	 * @return an array containing the next n characters, not null
+	 * @throws ParsingException if there is no more available data
+	 */
 	char[] readChars(int n);
 
+	/**
+	 * Reads all the characters until a character contained in {@code stop} is reached, and returns the
+	 * {@link CharsWrapper} that contains all the characters before the stop.
+	 *
+	 * @param stop the characters to stop at
+	 * @return a CharsWrapper that contains all the characters read before the stop
+	 * @throws ParsingException if there is no more available data
+	 */
 	CharsWrapper readCharUntil(char[] stop);
+
+	/**
+	 * Returns the next character, without moving the reading position forward. After a call to
+	 * {@code seek()}, the method {@link #read()} will return the exact same character.
+	 * This method throws an exception if there is no more available data.
+	 *
+	 * @return the next character
+	 * @throws ParsingException if there is no more available data
+	 */
+	char seekChar();
 }

core/src/main/java/com/electronwill/nightconfig/core/serialization/CharacterOutput.java

@@ -1,12 +1,40 @@
 package com.electronwill.nightconfig.core.serialization;
 
 /**
+ * Interface for outputs of characters.
+ *
  * @author TheElectronWill
  */
 public interface CharacterOutput {
+	/**
+	 * Writes a character.
+	 *
+	 * @param c the character to write
+	 */
 	void write(char c);
 
-	void write(char[] chars);
+	/**
+	 * Writes an array of characters.
+	 *
+	 * @param chars the characters to write
+	 */
+	default void write(char[] chars) {
+		write(chars, 0, chars.length);
+	}
 
+	/**
+	 * Writes a portion of an array of characters.
+	 *
+	 * @param chars  the characters to write
+	 * @param offset the index to start at
+	 * @param length the number of characters to write
+	 */
+	void write(char[] chars, int offset, int length);
+
+	/**
+	 * Writes all the characters in the given String.
+	 *
+	 * @param s the string to write
+	 */
 	void write(String s);
 }

core/src/main/java/com/electronwill/nightconfig/core/serialization/CharsWrapper.java

@@ -3,11 +3,20 @@
 import java.util.Arrays;
 
 /**
+ * A simple, efficient implementation of CharSequence. To avoid data copying, its constructor doesn't
+ * perfom any copy of the char array.
+ *
  * @author TheElectronWill
  */
 public final class CharsWrapper implements CharSequence, Cloneable {
 	private final char[] chars;
 
+	/**
+	 * Creates a new CharsWrapper backed by the given char array. Any modification to the array is
+	 * reflected to the CharsWrapper and vice-versa.
+	 *
+	 * @param chars the char array to use
+	 */
 	public CharsWrapper(char[] chars) {
 		this.chars = chars;
 	}
@@ -53,11 +62,25 @@ public String toString() {
 		return new String(chars);
 	}
 
+	/**
+	 * Checks if this CharsWrapper contains the specified character.
+	 *
+	 * @param c the character to look for
+	 * @return true if it contains the character, false if it does not
+	 */
 	public boolean contains(char c) {
 		return indexOf(c) != -1;
 	}
 
+	/**
+	 * Returns the index within this CharsWrapper of the first occurrence of the specified character.
+	 * Returns -1 if this CharsWrapper doesn't contains the character.
+	 *
+	 * @param c the character to look for
+	 * @return the index of the first occurence of {@code c}, or {@code -1} if not found.
+	 */
 	public int indexOf(char c) {
+		String a;
 		for (int i = 0; i < chars.length; i++) {
 			char ch = chars[i];
 			if (ch == c)
@@ -66,32 +89,61 @@ public int indexOf(char c) {
 		return -1;
 	}
 
+	/**
+	 * Returns the underlying char array that contains the CharsWrapper's characters. Any modification to
+	 * the array is reflected to the CharsWrapper and vice-versa.
+	 *
+	 * @return the underlying char array
+	 */
 	char[] getChars() {
 		return chars;
 	}
 
+	/**
+	 * Builder class for constructing CharsWrappers.
+	 */
 	public static class Builder implements CharacterOutput {
 		private char[] data;
 		private int cursor = 0;
 
+		/**
+		 * Creates a new CharsWrapper's builder with the specified initial capacity.
+		 *
+		 * @param initialCapacity the initial capacity
+		 */
 		public Builder(int initialCapacity) {
 			this.data = new char[initialCapacity];
 		}
 
+		/**
+		 * Ensures that {@code data} is large enough to contain {@code capacity} characters.
+		 *
+		 * @param capacity the minimum capacity to ensure
+		 */
 		private void ensureCapacity(int capacity) {
 			if (data.length < capacity) {
 				int newCapacity = Math.max(capacity, data.length * 2);
 				data = Arrays.copyOf(data, newCapacity);
 			}
 		}
 
+		/**
+		 * Appends a character to this builder.
+		 *
+		 * @param c the character to append
+		 * @return this builder
+		 */
 		public Builder append(char c) {
-			ensureCapacity(cursor + 1);
-			data[cursor] = c;
-			cursor++;
+			write(c);
 			return this;
 		}
 
+		/**
+		 * Appends a CharSequence to this builder.
+		 *
+		 * @param sequence the sequence to append
+		 * @return this builder
+		 */
 		public Builder append(CharSequence sequence) {
 			final int length = sequence.length();//caches the length for better performance.
 			// The sequence must not change between this point and the end of the loop!
@@ -103,32 +155,69 @@ public Builder append(CharSequence sequence) {
 			return this;
 		}
 
+		/**
+		 * Appends a char array to this builder.
+		 *
+		 * @param chars the array to append
+		 * @return this builder
+		 */
 		public Builder append(char[] chars) {
 			return append(chars, 0, chars.length);
 		}
 
+		/**
+		 * Appends a portion of a char array to this builder.
+		 *
+		 * @param chars  the array to append
+		 * @param start  the index to start at
+		 * @param length the number of characters to append
+		 * @return this builder
+		 */
 		public Builder append(char[] chars, int start, int length) {
-			ensureCapacity(cursor + length);
-			System.arraycopy(chars, start, data, cursor, length);
-			cursor += length;
+			write(chars, start, length);
 			return this;
 		}
 
+		/**
+		 * Appends the string representation of an object to this builder. This is equivalent to {@code
+		 * append(String.valueOf(o))}.
+		 *
+		 * @param o the object to append
+		 * @return this builder
+		 */
 		public Builder append(Object o) {
 			return append(String.valueOf(o));
 		}
 
+		/**
+		 * Appends multiple objects to this builder. This is equivalent to calling {@code append(String
+		 * .valueOf (o))} in a loop.
+		 *
+		 * @param objects the objects to append
+		 * @return this builder
+		 */
 		public Builder append(Object... objects) {
 			for (Object o : objects) {
 				append(o);
 			}
 			return this;
 		}
 
+		/**
+		 * Builds a CharsWrapper with the content of this builder. The content is NOT copied but directly
+		 * used as it is.
+		 *
+		 * @return a new CharsWrapper with the content of this builder
+		 */
 		public CharsWrapper build() {
 			return new CharsWrapper(data);
 		}
 
+		/**
+		 * {@inheritDoc}
+		 *
+		 * @deprecated use {@link #build()} instead
+		 */
 		@Override
 		@Deprecated
 		public String toString() {
@@ -137,12 +226,16 @@ public String toString() {
 
 		@Override
 		public void write(char c) {
-			append(c);
+			ensureCapacity(cursor + 1);
+			data[cursor] = c;
+			cursor++;
 		}
 
 		@Override
-		public void write(char[] chars) {
-			append(chars);
+		public void write(char[] chars, int offset, int length) {
+			ensureCapacity(cursor + length);
+			System.arraycopy(chars, offset, data, cursor, length);
+			cursor += length;
 		}
 
 		@Override