Merge pull request #1380 from katzyn/docs

Improve documentation of intervals

h2/src/docsrc/help/help.csv

@@ -3048,7 +3048,26 @@ and ""ResultSet.getObject(..)"" or ""ResultSet.getString(..)"" to retrieve the v
 GEOMETRY
 "
 
-"Data Types","INTERVAL YEAR Type","
+"Data Types","INTERVAL Types","
+intervalYearType | intervalMonthType | intervalDayType
+    | intervalHourType| intervalMinuteType | intervalSecondType
+    | intervalYearToMonthType | intervalDayToHourType
+    | intervalDayToMinuteType | intervalDayToSecondType
+    | intervalHourToMinuteType | intervalHourToSecondType
+    | intervalMinuteToSecondType
+","
+Interval data types.
+There are two classes of intervals. Year-month intervals can store years or months.
+Day-time intervals can store days, hours, minutes, and seconds.
+Year-month intervals are comparable only with another year-month intervals.
+Day-time intervals are comparable only with another day-time intervals.
+
+Mapped to ""org.h2.api.Interval"".
+","
+INTERVAL DAY TO SECOND
+"
+
+"Interval Data Types","INTERVAL YEAR Type","
 INTERVAL YEAR [ ( precisionInt ) ]
 ","
 Interval data type.
@@ -3059,7 +3078,7 @@ Mapped to ""org.h2.api.Interval"".
 INTERVAL YEAR
 "
 
-"Data Types","INTERVAL MONTH Type","
+"Interval Data Types","INTERVAL MONTH Type","
 INTERVAL MONTH [ ( precisionInt ) ]
 ","
 Interval data type.
@@ -3070,7 +3089,7 @@ Mapped to ""org.h2.api.Interval"".
 INTERVAL MONTH
 "
 
-"Data Types","INTERVAL DAY Type","
+"Interval Data Types","INTERVAL DAY Type","
 INTERVAL DAY [ ( precisionInt ) ]
 ","
 Interval data type.
@@ -3082,7 +3101,7 @@ Mapped to ""org.h2.api.Interval"".
 INTERVAL DAY
 "
 
-"Data Types","INTERVAL HOUR Type","
+"Interval Data Types","INTERVAL HOUR Type","
 INTERVAL HOUR [ ( precisionInt ) ]
 ","
 Interval data type.
@@ -3094,7 +3113,7 @@ Mapped to ""org.h2.api.Interval"".
 INTERVAL HOUR
 "
 
-"Data Types","INTERVAL MINUTE Type","
+"Interval Data Types","INTERVAL MINUTE Type","
 INTERVAL MINUTE [ ( precisionInt ) ]
 ","
 Interval data type.
@@ -3106,7 +3125,7 @@ Mapped to ""org.h2.api.Interval"".
 INTERVAL MINUTE
 "
 
-"Data Types","INTERVAL SECOND Type","
+"Interval Data Types","INTERVAL SECOND Type","
 INTERVAL SECOND [ ( precisionInt [, fractionalPrecisionInt ] ) ]
 ","
 Interval data type.
@@ -3119,7 +3138,7 @@ Mapped to ""org.h2.api.Interval"".
 INTERVAL SECOND
 "
 
-"Data Types","INTERVAL YEAR TO MONTH Type","
+"Interval Data Types","INTERVAL YEAR TO MONTH Type","
 INTERVAL YEAR [ ( precisionInt ) ] TO MONTH
 ","
 Interval data type.
@@ -3130,7 +3149,7 @@ Mapped to ""org.h2.api.Interval"".
 INTERVAL YEAR TO MONTH
 "
 
-"Data Types","INTERVAL DAY TO HOUR Type","
+"Interval Data Types","INTERVAL DAY TO HOUR Type","
 INTERVAL DAY [ ( precisionInt ) ] TO HOUR
 ","
 Interval data type.
@@ -3142,7 +3161,7 @@ Mapped to ""org.h2.api.Interval"".
 INTERVAL DAY TO HOUR
 "
 
-"Data Types","INTERVAL DAY TO MINUTE Type","
+"Interval Data Types","INTERVAL DAY TO MINUTE Type","
 INTERVAL DAY [ ( precisionInt ) ] TO MINUTE
 ","
 Interval data type.
@@ -3154,7 +3173,7 @@ Mapped to ""org.h2.api.Interval"".
 INTERVAL DAY TO MINUTE
 "
 
-"Data Types","INTERVAL DAY TO SECOND Type","
+"Interval Data Types","INTERVAL DAY TO SECOND Type","
 INTERVAL DAY [ ( precisionInt ) ] TO SECOND [ ( fractionalPrecisionInt ) ]
 ","
 Interval data type.
@@ -3167,7 +3186,7 @@ Mapped to ""org.h2.api.Interval"".
 INTERVAL DAY TO SECOND
 "
 
-"Data Types","INTERVAL HOUR TO MINUTE Type","
+"Interval Data Types","INTERVAL HOUR TO MINUTE Type","
 INTERVAL HOUR [ ( precisionInt ) ] TO MINUTE
 ","
 Interval data type.
@@ -3179,7 +3198,7 @@ Mapped to ""org.h2.api.Interval"".
 INTERVAL HOUR TO MINUTE
 "
 
-"Data Types","INTERVAL HOUR TO SECOND Type","
+"Interval Data Types","INTERVAL HOUR TO SECOND Type","
 INTERVAL HOUR [ ( precisionInt ) ] TO SECOND [ ( fractionalPrecisionInt ) ]
 ","
 Interval data type.
@@ -3192,8 +3211,8 @@ Mapped to ""org.h2.api.Interval"".
 INTERVAL HOUR TO SECOND
 "
 
-"Data Types","INTERVAL MINUTE TO SECOND Type","
-INTERVAL * [ ( precisionInt ) ] TO SECOND [ ( fractionalPrecisionInt ) ]
+"Interval Data Types","INTERVAL MINUTE TO SECOND Type","
+INTERVAL MINUTE [ ( precisionInt ) ] TO SECOND [ ( fractionalPrecisionInt ) ]
 ","
 Interval data type.
 If leading field precision is specified it should be from 1 to 18, 2 is default.

h2/src/docsrc/html/datatypes.html

@@ -71,6 +71,28 @@ syntax-end -->
 <p class="notranslate">${item.example}</p>
 </c:forEach>
 
+<h2>Interval Data Types</h2>
+
+<c:forEach var="item" items="intervalDataTypes">
+<h3 id="${item.link}" class="notranslate" onclick="switchBnf(this)">${item.topic}</h3>
+<!-- railroad-start -->
+<pre name="bnf" style="display: none">
+${item.syntax}
+</pre>
+<div name="railroad">
+${item.railroad}
+</div>
+<!-- railroad-end -->
+<!-- syntax-start
+<pre>
+${item.syntax}
+</pre>
+syntax-end -->
+<p>${item.text}</p>
+<p>Example:</p>
+<p class="notranslate">${item.example}</p>
+</c:forEach>
+
 <!--[if lte IE 7]><script language="javascript">switchBnf(null);</script><![endif]-->
 
 <!-- [close] { --></div></td></tr></table><!-- } --><!-- analytics --></body></html>

h2/src/docsrc/javadoc/classes.html

@@ -38,6 +38,7 @@ org.h2.jdbc<br />
 <a href="org/h2/jdbc/JdbcResultSetMetaData.html" target="javadoc">ResultSetMetaData</a><br />
 <a href="org/h2/jdbc/JdbcSavepoint.html" target="javadoc">Savepoint</a><br />
 <a href="org/h2/jdbc/JdbcSQLException.html" target="javadoc">SQLException</a><br />
+<a href="org/h2/jdbc/JdbcSQLXML.html" target="javadoc">SQLXML</a><br />
 <a href="org/h2/jdbc/JdbcStatement.html" target="javadoc">Statement</a><br />
 org.h2.jdbcx<br />
 <a href="org/h2/jdbcx/JdbcConnectionPool.html" target="javadoc">JdbcConnectionPool</a><br />
@@ -74,10 +75,14 @@ org.h2.tools<br />
 
 <b>Interfaces</b><br />
 org.h2.api<br />
+<a href="org/h2/api/Aggregate.html" target="javadoc">Aggregate</a><br />
 <a href="org/h2/api/AggregateFunction.html" target="javadoc">AggregateFunction</a><br />
 <a href="org/h2/api/DatabaseEventListener.html" target="javadoc">DatabaseEventListener</a><br />
 <a href="org/h2/api/ErrorCode.html" target="javadoc">ErrorCode</a><br />
+<a href="org/h2/api/Interval.html" target="javadoc">Interval</a><br />
+<a href="org/h2/api/IntervalQualifier.html" target="javadoc">IntervalQualifier</a><br />
 <a href="org/h2/api/TableEngine.html" target="javadoc">TableEngine</a><br />
+<a href="org/h2/api/TimestampWithTimeZone.html" target="javadoc">TimestampWithTimeZone</a><br />
 <a href="org/h2/api/Trigger.html" target="javadoc">Trigger</a><br />
 <br />
 

h2/src/main/org/h2/api/Interval.java

@@ -12,7 +12,7 @@ import org.h2.message.DbException;
 import org.h2.util.DateTimeUtils;
 
 /**
- * {@code INTERVAL} representation for result sets.
+ * INTERVAL representation for result sets.
  */
 public final class Interval {
 
@@ -410,7 +410,7 @@ public final class Interval {
     }
 
     /**
-     * Creates a new INTERVAL MINUTE TO SECOND
+     * Creates a new INTERVAL MINUTE TO SECOND.
      *
      * <p>
      * If both arguments are not equal to zero they should have the same sign.
@@ -427,7 +427,7 @@ public final class Interval {
     }
 
     /**
-     * Creates a new INTERVAL MINUTE TO SECOND
+     * Creates a new INTERVAL MINUTE TO SECOND.
      *
      * <p>
      * If both arguments are not equal to zero they should have the same sign.

h2/src/tools/org/h2/build/doc/BnfSyntax.java

@@ -68,9 +68,10 @@ public class BnfSyntax implements BnfVisitor {
             return token;
         }
         String page = "grammar.html";
-        if (found.getSection().startsWith("Data Types")) {
+        String section = found.getSection();
+        if (section.startsWith("Data Types") || section.startsWith("Interval Data Types")) {
             page = "datatypes.html";
-        } else if (found.getSection().startsWith("Functions")) {
+        } else if (section.startsWith("Functions")) {
             page = "functions.html";
         } else if (token.equals("@func@")) {
             return "<a href=\"functions.html\">Function</a>";

h2/src/tools/org/h2/build/doc/GenerateDoc.java

@@ -71,33 +71,35 @@ public class GenerateDoc {
         String help = "SELECT ROWNUM ID, * FROM CSVREAD('" +
                 IN_HELP + "', NULL, 'lineComment=#') WHERE SECTION ";
         map("commandsDML",
-                help + "= 'Commands (DML)' ORDER BY ID", true);
+                help + "= 'Commands (DML)' ORDER BY ID", true, false);
         map("commandsDDL",
-                help + "= 'Commands (DDL)' ORDER BY ID", true);
+                help + "= 'Commands (DDL)' ORDER BY ID", true, false);
         map("commandsOther",
-                help + "= 'Commands (Other)' ORDER BY ID", true);
+                help + "= 'Commands (Other)' ORDER BY ID", true, false);
         map("datetimeFields",
-                help + "= 'Datetime fields' ORDER BY ID", true);
+                help + "= 'Datetime fields' ORDER BY ID", true, false);
         map("otherGrammar",
-                help + "= 'Other Grammar' ORDER BY ID", true);
+                help + "= 'Other Grammar' ORDER BY ID", true, false);
         map("functionsAggregate",
-                help + "= 'Functions (Aggregate)' ORDER BY ID", true);
+                help + "= 'Functions (Aggregate)' ORDER BY ID", true, false);
         map("functionsNumeric",
-                help + "= 'Functions (Numeric)' ORDER BY ID", true);
+                help + "= 'Functions (Numeric)' ORDER BY ID", true, false);
         map("functionsString",
-                help + "= 'Functions (String)' ORDER BY ID", true);
+                help + "= 'Functions (String)' ORDER BY ID", true, false);
         map("functionsTimeDate",
-                help + "= 'Functions (Time and Date)' ORDER BY ID", true);
+                help + "= 'Functions (Time and Date)' ORDER BY ID", true, false);
         map("functionsSystem",
-                help + "= 'Functions (System)' ORDER BY ID", true);
+                help + "= 'Functions (System)' ORDER BY ID", true, false);
         map("dataTypes",
-                help + "LIKE 'Data Types%' ORDER BY SECTION, ID", true);
+                help + "LIKE 'Data Types%' ORDER BY SECTION, ID", true, true);
+        map("intervalDataTypes",
+                help + "LIKE 'Interval Data Types%' ORDER BY SECTION, ID", true, true);
         map("informationSchema", "SELECT TABLE_NAME TOPIC, " +
                 "GROUP_CONCAT(COLUMN_NAME " +
                 "ORDER BY ORDINAL_POSITION SEPARATOR ', ') SYNTAX " +
                 "FROM INFORMATION_SCHEMA.COLUMNS " +
                 "WHERE TABLE_SCHEMA='INFORMATION_SCHEMA' " +
-                "GROUP BY TABLE_NAME ORDER BY TABLE_NAME", false);
+                "GROUP BY TABLE_NAME ORDER BY TABLE_NAME", false, false);
         processAll("");
         conn.close();
     }
@@ -132,7 +134,7 @@ public class GenerateDoc {
         out.close();
     }
 
-    private void map(String key, String sql, boolean railroads)
+    private void map(String key, String sql, boolean railroads, boolean forDataTypes)
             throws Exception {
         ResultSet rs = null;
         Statement stat = null;
@@ -144,13 +146,17 @@ public class GenerateDoc {
             while (rs.next()) {
                 HashMap<String, String> map = new HashMap<>();
                 ResultSetMetaData meta = rs.getMetaData();
-                for (int i = 0; i < meta.getColumnCount(); i++) {
-                    String k = StringUtils.toLowerEnglish(meta.getColumnLabel(i + 1));
-                    String value = rs.getString(i + 1);
+                for (int i = 1; i <= meta.getColumnCount(); i++) {
+                    String k = StringUtils.toLowerEnglish(meta.getColumnLabel(i));
+                    String value = rs.getString(i);
                     value = value.trim();
                     map.put(k, PageParser.escapeHtml(value));
                 }
                 String topic = rs.getString("TOPIC");
+                // Convert "INT Type" to "INT" etc.
+                if (forDataTypes && topic.endsWith(" Type")) {
+                    map.put("topic", topic.substring(0, topic.length() - 5));
+                }
                 String syntax = rs.getString("SYNTAX").trim();
                 if (railroads) {
                     BnfRailroad r = new BnfRailroad();