Documentation/123-improve-code-examples

README.md

@@ -32,14 +32,14 @@ Goals:
 The following example gives you an idea about what you can do with the SQL Statement Builder. Check our [user guide](doc/user_guide/user_guide.md) for more details.
 
 ```java
-final Select select = StatementFactory.getInstance().select() //
-        .field("fieldA", "tableA.fieldB", "tableB.*");
+Select select = StatementFactory.getInstance().select()
+    .field("fieldA", "tableA.fieldB", "tableB.*");
 select.from().table("schemaA.tableA");
 select.limit(10);
-final StringRendererConfig config = StringRendererConfig.builder().quoteIdentifiers(true).build();
-final SelectRenderer renderer = new SelectRenderer(config);
+StringRendererConfig config = StringRendererConfig.builder().quoteIdentifiers(true).build();
+SelectRenderer renderer = new SelectRenderer(config);
 select.accept(renderer);
-final String sql = renderer.render();
+String sql = renderer.render();
 ```
 
 ## Table of Contents

doc/changes/changes_4.4.3.md

@@ -7,6 +7,10 @@ Code name: Internal refactorings on "More Predicates"
 * #117: Fixed sonar findings
 * #102: Refactored ColumnsDefinitionRenderer
 
+## Documentation
+
+* #123: Improved documentation
+
 ## Dependency Updates
 
 ### Test Dependency Updates

doc/system_requirements.md

@@ -373,11 +373,11 @@ ESB supports the following `SELECT` statement:
 
     derived-column = expression [as-clause]
 
-    expression = arithmetic-expression / column-reference / function  
+    expression = arithmetic-expression / column-reference / function
 
     table-expression = from-clause [where-clause] [limit-clause] [group-by-clause] [order-by-clause]
 
-    from-clause =  "FROM" table-reference 
+    from-clause =  "FROM" table-reference
 
     where-clause =  "WHERE" boolean-term
 

doc/user_guide/common_constructs/value_tables.md

@@ -4,8 +4,6 @@ Value tables are lists of content definitions for rows. They can appear in [`INS
 
 ## Defining Value Tables
 
-The class `ValueTable` contains multiple methods for defining value tables.
-
-The `appendRow()` methods allow adding all values for a complete row at once. They are especially useful in case all columns have the same type.
-
-The `add()` methods on the other hand amend the last row with an additional value.
+The class `ValueTable` contains multiple methods for defining value tables:
+* The `appendRow()` methods allow adding all values for a complete row at once. They are especially useful in case all columns have the same type.
+* The `add()` methods on the other hand amend the last row with an additional value.

doc/user_guide/list_of_supported_exasol_functions.md

@@ -3,12 +3,19 @@
 Here you can find a list of supported(or partly supported) functions for the Exasol database.
 
 - [Scalar Functions](#scalar-functions)
+  - [Numeric Functions](#numeric-functions)
+  - [String Functions](#string-functions)
+  - [Date/Time Functions](#datetime-functions)
+  - [Geospatial Functions](#geospatial-functions)
+  - [Bitwise Function](#bitwise-function)
+  - [Conversion Functions](#conversion-functions)
+  - [Other Scalar Functions](#other-scalar-functions)
 - [Aggregate Functions](#aggregate-functions)
 - [Analytic Functions](#analytic-functions)
 
 ## Scalar Functions
-     
-#### Numeric Functions
+
+### Numeric Functions
 
 - ABS
 - ACOS
@@ -40,9 +47,9 @@ Here you can find a list of supported(or partly supported) functions for the Exa
 - TAN
 - TANH
 - TRUNC
- 
-#### String Functions
-    
+
+### String Functions
+
 - ASCII
 - BIT_LENGTH
 - CHARACTER_LENGTH
@@ -81,7 +88,7 @@ Here you can find a list of supported(or partly supported) functions for the Exa
 - UNICODECHR
 - UPPER
 
-#### Date/Time Functions
+### Date/Time Functions
 
 - ADD_DAYS
 - ADD_HOURS
@@ -117,7 +124,7 @@ Here you can find a list of supported(or partly supported) functions for the Exa
 - YEAR
 - YEARS_BETWEEN
 
-#### Geospatial Functions
+### Geospatial Functions
 
 - ST_AREA
 - ST_BOUNDARY
@@ -160,7 +167,7 @@ Here you can find a list of supported(or partly supported) functions for the Exa
 - ST_X
 - ST_Y
 
-#### Bitwise Function
+### Bitwise Function
 
 - BIT_AND
 - BIT_CHECK
@@ -174,7 +181,7 @@ Here you can find a list of supported(or partly supported) functions for the Exa
 - BIT_TO_NUM
 - BIT_XOR
 
-#### Conversion Functions
+### Conversion Functions
 
 - IS_NUMBER
 - IS_DATE
@@ -189,7 +196,7 @@ Here you can find a list of supported(or partly supported) functions for the Exa
 - TO_TIMESTAMP
 - TO_YMINTERVAL
 
-#### Other Scalar Functions
+### Other Scalar Functions
 
 - COALESCE
 - CURRENT_SCHEMA

doc/user_guide/rendering.md

@@ -2,28 +2,26 @@
 
 ## Creating the Renderer With Default Settings
 
-To render an SQL statement, you need to create an instance of the SQl  Statement Renderer (for example `CreateTableRenderer`) using the `create()` method of
-the Renderer class.
+To render an SQL statement, you need to create an instance of the SQL Statement Renderer (for example `CreateTableRenderer`) using the `create()` method of the Renderer class:
 
 ```java
-final CreateTableRenderer renderer = CreateTableRenderer.create();
+CreateTableRenderer renderer = CreateTableRenderer.create();
 ```
 
 ## Customizing Rendering 
 
-If you need more control over the rendering process, you can create you own configuration
+If you need more control over the rendering process, you can create you own configuration.
 
 When you add a custom configuration, you need to pass an instance to the `create()` method. 
 
 ```java
-final StringRendererConfig config = StringRendererConfig.builder().lowerCase(true).build();
-final CreateTableRenderer renderer = CreateTableRenderer.create(config);
+StringRendererConfig config = StringRendererConfig.builder().lowerCase(true).build();
+CreateTableRenderer renderer = CreateTableRenderer.create(config);
 ```
-## Rendering Statements
 
+## Rendering Statements
 
-Next, call `accept()` method of the statement class (for example `CreateTable`) instance and pass the renderer as
-an argument.
+Next, call `accept()` method of the statement class (for example `CreateTable`) instance and pass the renderer as an argument.
 
 ```java
 createTable.accept(renderer);

doc/user_guide/statements/create_schema.md

@@ -1,11 +1,10 @@
 # CREATE SCHEMA
 
-The `CreateSchema` class of the SQL Statement Builder provides an entry 
-point to defining a CREATE SCHEMA SQL statement.
+The `CreateSchema` class of the SQL Statement Builder provides an entry point to defining a [`CREATE SCHEMA`](https://docs.exasol.com/sql/create_schema.htm) SQL statement.
 
 ## Usage
 
-1. Create an instance of the `CreateSchema` class through the `StatementFactory`
+1. Create an instance of the `CreateSchema` class through the `StatementFactory`:
 
   ```java
   CreateSchema createSchema = StatementFactory.getInstance().createSchema("schemaName");
@@ -18,7 +17,7 @@ point to defining a CREATE SCHEMA SQL statement.
   ```java
   CreateSchema createSchema = StatementFactory.getInstance().createSchema("schemaName");
 
-  //optional step: add config
+  // optional step: add configuration
   StringRendererConfig config = StringRendererConfig.builder().lowerCase(true).build();
   CreateSchemaRenderer renderer = CreateSchemaRenderer.create(config);
   createSchema.accept(renderer);

doc/user_guide/statements/create_table.md

@@ -1,11 +1,10 @@
 # CREATE TABLE
 
-The `CreateTable` class of the SQL Statement Builder provides an entry 
-point to defining a CREATE TABLE SQL statement.
+The `CreateTable` class of the SQL Statement Builder provides an entry point to defining a [`CREATE TABLE`](https://docs.exasol.com/sql/create_table.htm) SQL statement.
 
 ## Usage
 
-1. Create an instance of the `CreateTable` class through the `StatementFactory`
+1. Create an instance of the `CreateTable` class through the `StatementFactory`:
 
   ```java
   CreateTable createTable = StatementFactory.getInstance().createTable("tableName");
@@ -23,9 +22,7 @@ point to defining a CREATE TABLE SQL statement.
              .booleanColumn("col_boolean");
   ```
 
-  Please keep in mind that the column name is required when creating a column.
-  Additionally, some column types require extra parameters, for instance
-  `VARCHAR`.
+  Please keep in mind that the column name is required when creating a column. Additionally, some column types require extra parameters, for instance `VARCHAR`.
 
   **Currently, the following column types are supported:**
 
@@ -42,7 +39,7 @@ point to defining a CREATE TABLE SQL statement.
   |``TIMESTAMP WITH LOCAL TIME ZONE``| ``false``          | `createTable.timestampWithLocalTimeZoneColumn("col_tswithzone")` |
   |``VARCHAR``                       | ``true``           | `createTable.varcharColumn("col_varchar", 100)`                  |
 
-  You can find more information about the column types in the SQL Statement Builder's JavaDoc API description.
+  You can find more information about the column types in the SQL Statement Builder's [JavaDoc API description](https://exasol.github.io/sql-statement-builder/com/exasol/datatype/type/package-summary.html).
 
 3. Render the instance of `CreateTable` class. Click [here](../rendering.md) for more information on Rendering SQL Statement.
 
@@ -56,12 +53,12 @@ point to defining a CREATE TABLE SQL statement.
              .charColumn("col_char", 10)
              .booleanColumn("col_boolean");
 
-  //optional step: add config
+  // optional step: add configuration
   StringRendererConfig config = StringRendererConfig.builder().lowerCase(true).build();
   CreateTableRenderer renderer = CreateTableRenderer.create(config);
   createTable.accept(renderer);
 
   String renderedString = renderer.render();
   ```
-  
-Please check [API documentation](https://exasol.github.io/sql-statement-builder/com/exasol/sql/ddl/create/CreateTable.html) for more details.
+
+Please check the [API documentation](https://exasol.github.io/sql-statement-builder/com/exasol/sql/ddl/create/CreateTable.html) for more details.

doc/user_guide/statements/drop_schema.md

@@ -1,7 +1,6 @@
 # DROP SCHEMA
 
-The `DropSchema` class of the SQL Statement Builder provides an entry 
-point to defining a DROP SCHEMA SQL statement.
+The `DropSchema` class of the SQL Statement Builder provides an entry point to defining a [`DROP SCHEMA`](https://docs.exasol.com/sql/drop_schema.htm) SQL statement.
 
 ## Usage
 
@@ -24,8 +23,7 @@ point to defining a DROP SCHEMA SQL statement.
     ```java
     dropSchema.ifExists().cascade();
     ```
-    Please do not use methods `cascade()` and `restrict()` on the same object.
-    If both these options are used on the same object, `IllegalArgumentException` will be thrown.
+    Please do not use methods `cascade()` and `restrict()` on the same object. If both these options are used on the same object, `IllegalArgumentException` will be thrown.
 
 3. Render the instance of `DropSchema` class. Click [here](../rendering.md) for more information on Rendering SQL Statement.
 
@@ -34,13 +32,13 @@ point to defining a DROP SCHEMA SQL statement.
     ```java
      DropSchema dropSchema = StatementFactory.getInstance().dropSchema("schemaName");
 
-     //optional step: add additional clauses
+     // optional step: add additional clauses
      dropSchema.ifExists().cascade();
-     //or
+     // or
      dropSchema.ifExists().restrict();
 
-     //Rendering
-     //optional step: add config
+     // Rendering
+     // optional step: add configuration
      StringRendererConfig config = StringRendererConfig.builder().lowerCase(true).build();
 
      DropSchemaRenderer renderer = DropSchemaRenderer.create(config);

doc/user_guide/statements/drop_table.md

@@ -1,7 +1,6 @@
 # DROP TABLE
 
-The `DropTable` class of the SQL Statement Builder provides an entry 
-point to defining a DROP TABLE SQL statement.
+The `DropTable` class of the SQL Statement Builder provides an entry point to defining a [`DROP TABLE`](https://docs.exasol.com/sql/drop_table.htm) SQL statement.
 
 ## Usage
 
@@ -26,19 +25,19 @@ point to defining a DROP TABLE SQL statement.
 
 3. Render the instance of `DropTable` class. Click [here](../rendering.md) for more information on Rendering SQL Statement.
 
-   - The complete example code
+   The complete example code:
 
     ```java
-      DropTable dropTable = StatementFactory.getInstance().dropTable("tableName");
+    DropTable dropTable = StatementFactory.getInstance().dropTable("tableName");
 
-     //optional step: add additional clauses
-     dropTable.ifExists().cascadeConstraints();
+    // optional step: add additional clauses
+    dropTable.ifExists().cascadeConstraints();
 
-     //Rendering
-     //optional step: add config
-     StringRendererConfig config = StringRendererConfig.builder().lowerCase(true).build();
+    // Rendering
+    // optional step: add configuration
+    StringRendererConfig config = StringRendererConfig.builder().lowerCase(true).build();
 
-     DropTableRenderer renderer = DropTableRenderer.create(config);
-     dropTable.accept(renderer);
-     String renderedString = renderer.render();
-     ```
+    DropTableRenderer renderer = DropTableRenderer.create(config);
+    dropTable.accept(renderer);
+    String renderedString = renderer.render();
+    ```