1.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/CLIOptions.java	Fri Jan 10 20:13:16 2014 +0100
     1.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/CLIOptions.java	Fri Jan 10 23:21:28 2014 +0100
     1.3 @@ -34,6 +34,8 @@
     1.4  import java.util.regex.PatternSyntaxException;
     1.5  
     1.6  /**
     1.7 + * Holds options from command line, validates them, combines with configuration and provides derived
     1.8 + * objects.
     1.9   *
    1.10   * @author Ing. František Kučera (frantovo.cz)
    1.11   */
    1.12 @@ -43,7 +45,7 @@
    1.13  	public static final String DEFAULT_NAME_SUFFIX = "(?=([^\\w]|$))";
    1.14  	private String sql;
    1.15  	private String databaseName;
    1.16 -	private Set<String> databaseNameToTest = new HashSet<>();
    1.17 +	private Set<String> databaseNamesToTest = new HashSet<>();
    1.18  	private String namePrefix = DEFAULT_NAME_PREFIX;
    1.19  	private String nameSuffix = DEFAULT_NAME_SUFFIX;
    1.20  	private String formatterName;
    1.21 @@ -90,7 +92,7 @@
    1.22  			if (!equalz(nameSuffix, DEFAULT_NAME_SUFFIX)) {
    1.23  				e.addProblem(new InvalidOptionsException.OptionProblem("Do not specify name suffix if just showing info."));
    1.24  			}
    1.25 -			if (showInfo.contains(InfoType.CONNECTION) && databaseNameToTest.isEmpty()) {
    1.26 +			if (showInfo.contains(InfoType.CONNECTION) && databaseNamesToTest.isEmpty()) {
    1.27  				e.addProblem(new InvalidOptionsException.OptionProblem("Please specify which database should be tested."));
    1.28  			}
    1.29  		}
    1.30 @@ -232,12 +234,12 @@
    1.31  		return showInfo;
    1.32  	}
    1.33  
    1.34 -	public Set<String> getDatabaseNameToTest() {
    1.35 -		return databaseNameToTest;
    1.36 +	public Set<String> getDatabaseNamesToTest() {
    1.37 +		return databaseNamesToTest;
    1.38  	}
    1.39  
    1.40 -	public void addDatabaseNameToTest(String databaseNameToTest) {
    1.41 -		this.databaseNameToTest.add(databaseNameToTest);
    1.42 +	public void addDatabaseNamesToTest(String databaseNameToTest) {
    1.43 +		this.databaseNamesToTest.add(databaseNameToTest);
    1.44  	}
    1.45  
    1.46  	public SQLCommand getSQLCommand() {

     2.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/CLIParser.java	Fri Jan 10 20:13:16 2014 +0100
     2.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/CLIParser.java	Fri Jan 10 23:21:28 2014 +0100
     2.3 @@ -25,6 +25,9 @@
     2.4  import java.util.Map;
     2.5  
     2.6  /**
     2.7 + * Converts command line arguments from String array to object.
     2.8 + * Checks basic constraints (if only supported options are used and if they have correct number of
     2.9 + * parameters)
    2.10   *
    2.11   * @author Ing. František Kučera (frantovo.cz)
    2.12   */
    2.13 @@ -127,7 +130,7 @@
    2.14  					break;
    2.15  				case Tokens.INFO_CONNECTION:
    2.16  					options.addShowInfo(InfoType.CONNECTION);
    2.17 -					options.addDatabaseNameToTest(fetchNext(args, ++i));
    2.18 +					options.addDatabaseNamesToTest(fetchNext(args, ++i));
    2.19  					break;
    2.20  				default:
    2.21  					throw new CLIParserException("Unknown option: " + arg);

     3.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/CLIStarter.java	Fri Jan 10 20:13:16 2014 +0100
     3.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/CLIStarter.java	Fri Jan 10 23:21:28 2014 +0100
     3.3 @@ -45,6 +45,7 @@
     3.4  import javax.xml.bind.Unmarshaller;
     3.5  
     3.6  /**
     3.7 + * Entry point of the command line interface of SQL-DK.
     3.8   *
     3.9   * @author Ing. František Kučera (frantovo.cz)
    3.10   */
    3.11 @@ -53,6 +54,7 @@
    3.12  	// help:exit-codes
    3.13  	public static final int EXIT_SUCCESS = 0; // doc:success
    3.14  	public static final int EXIT_UNEXPECTED_ERROR = 1; // doc:unexpected error (probably bug)
    3.15 +	// 2 is reserved: http://www.tldp.org/LDP/abs/html/exitcodes.html#EXITCODESREF
    3.16  	public static final int EXIT_SQL_ERROR = 3; // doc:SQL error
    3.17  	public static final int EXIT_CLI_PARSE_ERROR = 4; // doc:CLI options parse error
    3.18  	public static final int EXIT_CLI_VALIDATE_ERROR = 5; // doc:CLI options validation error

     4.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/ColorfulPrintWriter.java	Fri Jan 10 20:13:16 2014 +0100
     4.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/ColorfulPrintWriter.java	Fri Jan 10 23:21:28 2014 +0100
     4.3 @@ -26,6 +26,10 @@
     4.4  import java.util.EnumSet;
     4.5  
     4.6  /**
     4.7 + * PrintWriter with convenience methods for printing color and formatted text.
     4.8 + *
     4.9 + * Uses ANSI Escape Sequences.
    4.10 + * See: http://www.tldp.org/HOWTO/Bash-Prompt-HOWTO/x329.html
    4.11   *
    4.12   * @author Ing. František Kučera (frantovo.cz)
    4.13   */

     5.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/DatabaseConnection.java	Fri Jan 10 20:13:16 2014 +0100
     5.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/DatabaseConnection.java	Fri Jan 10 23:21:28 2014 +0100
     5.3 @@ -34,6 +34,11 @@
     5.4  import java.util.logging.Logger;
     5.5  
     5.6  /**
     5.7 + * Represents connected database. Is derived from {@linkplain DatabaseDefinition}.
     5.8 + * Wraps {@linkplain Connection}.
     5.9 + *
    5.10 + * Is responsible for executing {@linkplain SQLCommand} and passing results to the
    5.11 + * {@linkplain Formatter}.
    5.12   *
    5.13   * @author Ing. František Kučera (frantovo.cz)
    5.14   */

     6.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/InfoLister.java	Fri Jan 10 20:13:16 2014 +0100
     6.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/InfoLister.java	Fri Jan 10 23:21:28 2014 +0100
     6.3 @@ -155,7 +155,7 @@
     6.4  				new HeaderField("connected", SQLType.BOOLEAN));
     6.5  		List<Object[]> data = new ArrayList<>();
     6.6  
     6.7 -		for (String dbName : options.getDatabaseNameToTest()) {
     6.8 +		for (String dbName : options.getDatabaseNamesToTest()) {
     6.9  			data.add(testConnection(dbName));
    6.10  		}
    6.11  

     7.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/Parameter.java	Fri Jan 10 20:13:16 2014 +0100
     7.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/Parameter.java	Fri Jan 10 23:21:28 2014 +0100
     7.3 @@ -20,6 +20,7 @@
     7.4  import java.sql.Types;
     7.5  
     7.6  /**
     7.7 + * Parameter for {@linkplain SQLCommand}
     7.8   *
     7.9   * @author Ing. František Kučera (frantovo.cz)
    7.10   */

     8.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/SQLCommand.java	Fri Jan 10 20:13:16 2014 +0100
     8.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/SQLCommand.java	Fri Jan 10 23:21:28 2014 +0100
     8.3 @@ -23,6 +23,7 @@
     8.4  import java.util.List;
     8.5  
     8.6  /**
     8.7 + * Represents SQL string and its parameters (if there are any).
     8.8   *
     8.9   * @author Ing. František Kučera (frantovo.cz)
    8.10   */

     9.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/SQLCommandNamed.java	Fri Jan 10 20:13:16 2014 +0100
     9.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/SQLCommandNamed.java	Fri Jan 10 23:21:28 2014 +0100
     9.3 @@ -30,6 +30,7 @@
     9.4  import java.util.regex.PatternSyntaxException;
     9.5  
     9.6  /**
     9.7 + * Has named parameters.
     9.8   *
     9.9   * @author Ing. František Kučera (frantovo.cz)
    9.10   */

    10.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/SQLCommandNumbered.java	Fri Jan 10 20:13:16 2014 +0100
    10.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/SQLCommandNumbered.java	Fri Jan 10 23:21:28 2014 +0100
    10.3 @@ -23,6 +23,7 @@
    10.4  import java.util.List;
    10.5  
    10.6  /**
    10.7 + * Has ordinal/numbered parameters.
    10.8   *
    10.9   * @author Ing. František Kučera (frantovo.cz)
   10.10   */

    11.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/SQLType.java	Fri Jan 10 20:13:16 2014 +0100
    11.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/SQLType.java	Fri Jan 10 23:21:28 2014 +0100
    11.3 @@ -20,6 +20,7 @@
    11.4  import java.sql.Types;
    11.5  
    11.6  /**
    11.7 + * Data types of SQL parameters.
    11.8   *
    11.9   * @author Ing. František Kučera (frantovo.cz)
   11.10   */

    12.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/batch/Batch.java	Fri Jan 10 20:13:16 2014 +0100
    12.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/batch/Batch.java	Fri Jan 10 23:21:28 2014 +0100
    12.3 @@ -20,6 +20,7 @@
    12.4  import info.globalcode.sql.dk.SQLCommand;
    12.5  
    12.6  /**
    12.7 + * Iterator which reads SQL commands from encoded (serialized) batch.
    12.8   *
    12.9   * @author Ing. František Kučera (frantovo.cz)
   12.10   */

    13.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/configuration/Configuration.java	Fri Jan 10 20:13:16 2014 +0100
    13.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/configuration/Configuration.java	Fri Jan 10 23:21:28 2014 +0100
    13.3 @@ -35,6 +35,7 @@
    13.4  import javax.xml.bind.annotation.XmlTransient;
    13.5  
    13.6  /**
    13.7 + * Object representation of user configuration loaded from XML.
    13.8   *
    13.9   * @author Ing. František Kučera (frantovo.cz)
   13.10   */

    14.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/configuration/ConfigurationProvider.java	Fri Jan 10 20:13:16 2014 +0100
    14.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/configuration/ConfigurationProvider.java	Fri Jan 10 23:21:28 2014 +0100
    14.3 @@ -18,6 +18,7 @@
    14.4  package info.globalcode.sql.dk.configuration;
    14.5  
    14.6  /**
    14.7 + * Use for lazy-loading of the configuration.
    14.8   *
    14.9   * @author Ing. František Kučera (frantovo.cz)
   14.10   */

    15.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/configuration/DatabaseDefinition.java	Fri Jan 10 20:13:16 2014 +0100
    15.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/configuration/DatabaseDefinition.java	Fri Jan 10 23:21:28 2014 +0100
    15.3 @@ -23,6 +23,7 @@
    15.4  import javax.xml.bind.annotation.XmlElement;
    15.5  
    15.6  /**
    15.7 + * Configured (but not yet connected) database connection.
    15.8   *
    15.9   * @author Ing. František Kučera (frantovo.cz)
   15.10   */
   15.11 @@ -81,7 +82,7 @@
   15.12  	}
   15.13  
   15.14  	/**
   15.15 -	 * @param properties ad-hoc properties from CLI options
   15.16 +	 * @param properties ad-hoc properties from CLI options (for the JDBC driver)
   15.17  	 */
   15.18  	public DatabaseConnection connect(Properties properties) throws SQLException {
   15.19  		return new DatabaseConnection(this, properties);

    16.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/configuration/FormatterDefinition.java	Fri Jan 10 20:13:16 2014 +0100
    16.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/configuration/FormatterDefinition.java	Fri Jan 10 23:21:28 2014 +0100
    16.3 @@ -27,6 +27,7 @@
    16.4  import javax.xml.bind.annotation.XmlElement;
    16.5  
    16.6  /**
    16.7 + * Configured (but not yet instantiated) formatter.
    16.8   *
    16.9   * @author Ing. František Kučera (frantovo.cz)
   16.10   */

    17.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/configuration/Properties.java	Fri Jan 10 20:13:16 2014 +0100
    17.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/configuration/Properties.java	Fri Jan 10 23:21:28 2014 +0100
    17.3 @@ -26,9 +26,8 @@
    17.4   * <p>List of configurables.</p>
    17.5   *
    17.6   * <p>Can be backed by defaults – if value for given name is nof found in this instance, we will
    17.7 - * look
    17.8 - * into defaults. Methods also accept defaultValue parameter – is used if property is nof found even
    17.9 - * in default properties.</p>
   17.10 + * look into defaults. Methods also accept defaultValue parameter – is used if property is nof found
   17.11 + * even in default properties.</p>
   17.12   *
   17.13   * <p>Typical use: </p>
   17.14   * <ul>

    18.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/formatting/AbstractFormatter.java	Fri Jan 10 20:13:16 2014 +0100
    18.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/formatting/AbstractFormatter.java	Fri Jan 10 23:21:28 2014 +0100
    18.3 @@ -25,6 +25,11 @@
    18.4  import java.util.Stack;
    18.5  
    18.6  /**
    18.7 + * <ol>
    18.8 + * <li>ensures integrity – if methods are called in correct order and context</li>
    18.9 + * <li>provides default implmentations of methods that does not produce any output for given
   18.10 + * events</li>
   18.11 + * </ol>
   18.12   *
   18.13   * @author Ing. František Kučera (frantovo.cz)
   18.14   */

    19.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/formatting/AbstractXmlFormatter.java	Fri Jan 10 20:13:16 2014 +0100
    19.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/formatting/AbstractXmlFormatter.java	Fri Jan 10 23:21:28 2014 +0100
    19.3 @@ -33,6 +33,14 @@
    19.4  import java.util.logging.Logger;
    19.5  
    19.6  /**
    19.7 + * <p>
    19.8 + * Provides helper methods for printing pretty intended and optionally colorful (syntax highlighted)
    19.9 + * XML output.
   19.10 + * </p>
   19.11 + *
   19.12 + * <p>
   19.13 + * Must be used with care – bad usage can lead to invalid XML (e.g. using undeclared namespaces).
   19.14 + * </p>
   19.15   *
   19.16   * @author Ing. František Kučera (frantovo.cz)
   19.17   */

    20.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/formatting/Formatter.java	Fri Jan 10 20:13:16 2014 +0100
    20.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/formatting/Formatter.java	Fri Jan 10 23:21:28 2014 +0100
    20.3 @@ -22,6 +22,9 @@
    20.4  import java.util.List;
    20.5  
    20.6  /**
    20.7 + * The formatter is responsible for printing the result sets and/or updates result (count of
    20.8 + * inserted/updated rows). The formatter can produce output in arbitrary format – text, some markup
    20.9 + * or even binary data.
   20.10   *
   20.11   * @author Ing. František Kučera (frantovo.cz)
   20.12   */

    21.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/formatting/FormatterContext.java	Fri Jan 10 20:13:16 2014 +0100
    21.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/formatting/FormatterContext.java	Fri Jan 10 23:21:28 2014 +0100
    21.3 @@ -21,6 +21,7 @@
    21.4  import java.io.OutputStream;
    21.5  
    21.6  /**
    21.7 + * To be passed from the SQL-DK core to the formatter.
    21.8   *
    21.9   * @author Ing. František Kučera (frantovo.cz)
   21.10   */

    22.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/formatting/TabularFormatter.java	Fri Jan 10 20:13:16 2014 +0100
    22.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/formatting/TabularFormatter.java	Fri Jan 10 23:21:28 2014 +0100
    22.3 @@ -25,8 +25,14 @@
    22.4  import java.util.List;
    22.5  
    22.6  /**
    22.7 + * <p>Prints human-readable output – tables of result sets and text messages with update counts.</p>
    22.8 + *
    22.9 + * <p>Longer values might break the table – overflow the cells – see alternative tabular formatters
   22.10 + * and the {@linkplain #PROPERTY_TRIM} property.</p>
   22.11   *
   22.12   * @author Ing. František Kučera (frantovo.cz)
   22.13 + * @see TabularPrefetchingFormatter
   22.14 + * @see TabularWrappingFormatter
   22.15   */
   22.16  public class TabularFormatter extends AbstractFormatter {
   22.17  

    23.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/formatting/TabularPrefetchingFormatter.java	Fri Jan 10 20:13:16 2014 +0100
    23.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/formatting/TabularPrefetchingFormatter.java	Fri Jan 10 23:21:28 2014 +0100
    23.3 @@ -21,10 +21,14 @@
    23.4  import java.util.List;
    23.5  
    23.6  /**
    23.7 + * <p>
    23.8   * Prefetches whole result set and computes column widths. Whole table is flushed at once in
    23.9   * {@linkplain #writeEndResultSet()}.
   23.10 + * </p>
   23.11   *
   23.12 - * Long values will not overflow the cells, but whole result set must be loaded into memory.
   23.13 + * <p>
   23.14 + * Long values will not overflow the cells, but whole result set must be loaded into the memory.
   23.15 + * </p>
   23.16   *
   23.17   * @author Ing. František Kučera (frantovo.cz)
   23.18   */

    24.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/formatting/TabularWrappingFormatter.java	Fri Jan 10 20:13:16 2014 +0100
    24.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/formatting/TabularWrappingFormatter.java	Fri Jan 10 23:21:28 2014 +0100
    24.3 @@ -25,6 +25,8 @@
    24.4  import static info.globalcode.sql.dk.Functions.repeat;
    24.5  
    24.6  /**
    24.7 + * Longer values are line-wrapped – the cell then contains multiple lines. Marks are added to
    24.8 + * signalize forced line ends (not present in original data).
    24.9   *
   24.10   * @author Ing. František Kučera (frantovo.cz)
   24.11   */

    25.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/formatting/XhtmlFormatter.java	Fri Jan 10 20:13:16 2014 +0100
    25.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/formatting/XhtmlFormatter.java	Fri Jan 10 23:21:28 2014 +0100
    25.3 @@ -36,6 +36,9 @@
    25.4  import javax.xml.namespace.QName;
    25.5  
    25.6  /**
    25.7 + * Prints result sets and parameters as tables, SQL as preformatted and updates counts as
    25.8 + * paragraphs. You can pick XHTML fragments (usually tabular data) and use it on your website or use
    25.9 + * whole output as preview or report.
   25.10   *
   25.11   * @author Ing. František Kučera (frantovo.cz)
   25.12   */

    26.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/formatting/XmlFormatter.java	Fri Jan 10 20:13:16 2014 +0100
    26.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/formatting/XmlFormatter.java	Fri Jan 10 23:21:28 2014 +0100
    26.3 @@ -29,6 +29,10 @@
    26.4  import javax.xml.namespace.QName;
    26.5  
    26.6  /**
    26.7 + * <p>Prints machine-readable output – XML document containing resultsets and updates count. Good
    26.8 + * choice for further processing – e.g. XSL transformation.</p>
    26.9 + *
   26.10 + * <p>TODO: XSD</p>
   26.11   *
   26.12   * @author Ing. František Kučera (frantovo.cz)
   26.13   */

    27.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/logging/ColorfulConsoleFormatter.java	Fri Jan 10 20:13:16 2014 +0100
    27.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/logging/ColorfulConsoleFormatter.java	Fri Jan 10 23:21:28 2014 +0100
    27.3 @@ -27,6 +27,7 @@
    27.4  import java.util.logging.LogRecord;
    27.5  
    27.6  /**
    27.7 + * For console/terminal log output. Log messages are printed in brief and colorful form.
    27.8   *
    27.9   * @author Ing. František Kučera (frantovo.cz)
   27.10   */

    28.1 --- a/java/sql-dk/src/info/globalcode/sql/dk/logging/LoggerInitializer.java	Fri Jan 10 20:13:16 2014 +0100
    28.2 +++ b/java/sql-dk/src/info/globalcode/sql/dk/logging/LoggerInitializer.java	Fri Jan 10 23:21:28 2014 +0100
    28.3 @@ -47,7 +47,7 @@
    28.4  
    28.5  
    28.6  		/**
    28.7 -		 * TODO: FileHandler – detailed logs in file in ~/sql-dk/log/…
    28.8 +		 * TODO: optional FileHandler – detailed logs in file in ~/sql-dk/log/…
    28.9  		 */
   28.10  	}
   28.11