From 84a71cfa721bfefd2edf08d5d278e4b8095d18f4 Mon Sep 17 00:00:00 2001
From: Gabor Szadovszky <gabor.szadovszky@cloudera.com>
Date: Mon, 26 Sep 2016 09:59:24 +0200
Subject: [PATCH 1/2] AVRO-1918 - Improve logical type documentation

---
 doc/src/content/xdocs/idl.xml                 | 22 +++++++++++++++++++
 .../org/apache/avro/specific/package.html     |  3 +++
 2 files changed, 25 insertions(+)

diff --git a/doc/src/content/xdocs/idl.xml b/doc/src/content/xdocs/idl.xml
index bd74b09f390..ba75d967aac 100644
--- a/doc/src/content/xdocs/idl.xml
+++ b/doc/src/content/xdocs/idl.xml
@@ -206,6 +206,7 @@ error Kaboom {
       <p>A type reference in Avro IDL must be one of:</p>
       <ul>
         <li>A primitive type</li>
+        <li>A logical type</li>
         <li>A named schema defined prior to this usage in the same Protocol</li>
         <li>A complex type (array, map, or union)</li>
       </ul>
@@ -218,6 +219,27 @@ error Kaboom {
         </p>
       </section>
 
+      <section id="logical_types">
+        <title>Logical Types</title>
+        <p>Some of the logical types supported by Avro's JSON format are also supported by Avro IDL.
+        The currently supported types are:
+        </p>
+        <ul>
+          <li><code>decimal</code> (logical type <a href="spec.html#Decimal"><code>decimal</code></a>)</li>
+          <li><code>date</code> (logical type <a href="spec.html#Date"><code>date</code></a>)</li>
+          <li><code>time_ms</code> (logical type <a href="spec.html#Time+%28millisecond+precision%29"><code>time-millis</code></a>)</li>
+          <li><code>timestamp-ms</code> (logical type <a href="spec.html#Timestamp+%28millisecond+precision%29"><code>timestamp-millis</code></a>)</li>
+        </ul>
+        <p>For example:</p>
+        <source>
+record JobFinished {
+  string jobid;
+  timestamp_ms finishTime;
+  decimal(9,2) finishRatio;
+}
+        </source>
+      </section>
+
       <section id="schema_references">
         <title>References to Named Schemata</title>
         <p>If a named schema has already been defined in the same Avro IDL file, it may be referenced by name
diff --git a/lang/java/avro/src/main/java/org/apache/avro/specific/package.html b/lang/java/avro/src/main/java/org/apache/avro/specific/package.html
index d9be484451f..7b027547ce6 100644
--- a/lang/java/avro/src/main/java/org/apache/avro/specific/package.html
+++ b/lang/java/avro/src/main/java/org/apache/avro/specific/package.html
@@ -31,6 +31,9 @@
 
 <li>Record, enum, and fixed schemas generate Java class definitions.</li>
 
+<li>If a Conversion instance is available for the related logical type,
+  the value will be mapped to the object returned by that Conversion.</li>
+
 <li>All other types are mapped as in the {@link org.apache.avro.generic
   generic} API.</li>
 

From 051c45ae423af975a58685232143a2ba9aa89004 Mon Sep 17 00:00:00 2001
From: Gabor Szadovszky <gabor.szadovszky@cloudera.com>
Date: Tue, 27 Sep 2016 10:31:12 +0200
Subject: [PATCH 2/2] AVRO-1918 (2) - doc extensions after review

---
 doc/src/content/xdocs/idl.xml                               | 6 ++++--
 .../src/main/java/org/apache/avro/specific/package.html     | 5 ++++-
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/doc/src/content/xdocs/idl.xml b/doc/src/content/xdocs/idl.xml
index ba75d967aac..c9a809f61de 100644
--- a/doc/src/content/xdocs/idl.xml
+++ b/doc/src/content/xdocs/idl.xml
@@ -228,12 +228,14 @@ error Kaboom {
           <li><code>decimal</code> (logical type <a href="spec.html#Decimal"><code>decimal</code></a>)</li>
           <li><code>date</code> (logical type <a href="spec.html#Date"><code>date</code></a>)</li>
           <li><code>time_ms</code> (logical type <a href="spec.html#Time+%28millisecond+precision%29"><code>time-millis</code></a>)</li>
-          <li><code>timestamp-ms</code> (logical type <a href="spec.html#Timestamp+%28millisecond+precision%29"><code>timestamp-millis</code></a>)</li>
+          <li><code>timestamp_ms</code> (logical type <a href="spec.html#Timestamp+%28millisecond+precision%29"><code>timestamp-millis</code></a>)</li>
         </ul>
         <p>For example:</p>
         <source>
-record JobFinished {
+record Job {
   string jobid;
+  date submitDate;
+  time_ms submitTime;
   timestamp_ms finishTime;
   decimal(9,2) finishRatio;
 }
diff --git a/lang/java/avro/src/main/java/org/apache/avro/specific/package.html b/lang/java/avro/src/main/java/org/apache/avro/specific/package.html
index 7b027547ce6..b331592755b 100644
--- a/lang/java/avro/src/main/java/org/apache/avro/specific/package.html
+++ b/lang/java/avro/src/main/java/org/apache/avro/specific/package.html
@@ -32,7 +32,10 @@
 <li>Record, enum, and fixed schemas generate Java class definitions.</li>
 
 <li>If a Conversion instance is available for the related logical type,
-  the value will be mapped to the object returned by that Conversion.</li>
+  the value will be mapped to the object returned by that Conversion. The
+  logical type conversions for {@code date}, {@code time-millis}, {@code
+  timestamp-millis} and {@code decimal} are pre-defined in the class {@link
+  org.apache.avro.compiler.specific.SpecificCompiler SpecificCompiler}.</li>
 
 <li>All other types are mapped as in the {@link org.apache.avro.generic
   generic} API.</li>