Improve documentation around next.jdbc.date-time

Expands the documentation around each place it is referenced. Expands 
the namespace docstring. Adds a mention of it to the result-set 
namespace docstring.

CHANGELOG.md

@@ -10,6 +10,7 @@ The following changes have been made to **master** since the 1.0.409 build:
 * Fixes #102 by allowing keywords or strings in `:return-keys`.
 * Fixes #101 by tightening the spec on a JDBC URL to correctly reflect that it must start with `jdbc:`.
 * Add support for calling `.getLoginTimeout`/`.setLoginTimeout` on the reified `DataSource` returned by `get-datasource` when called on a hash map "db-spec" or JDBC URL string.
+* Documentation improvements based on feedback (mostly from Slack).
 
 ## Stable Builds
 

doc/getting-started.md

@@ -363,7 +363,7 @@ In particular, PostgreSQL does not seem to perform a conversion from `java.util.
 
 If you are working with Java Time, some JDBC drivers will automatically convert `java.time.Instant` (and `java.time.LocalDate` and `java.time.LocalDateTime`) to a SQL data type automatically, but others will not. Requiring `next.jdbc.date-time` will enable those automatic conversions for all databases.
 
-> Note: `next.jdbc.date-time` does **not** provide automatic conversion of SQL data types to Clojure data types when reading result sets. If you want specific conversions to happen automatically, consider extending the `ReadableColumn` protocol, mentioned above.
+> Note: `next.jdbc.date-time` also provides functions you can call to enable automatic conversion of SQL date/timestamp types to Clojure data types when reading result sets. If you need specific conversions beyond that to happen automatically, consider extending the `ReadableColumn` protocol, mentioned above.
 
 ## Support from Specs
 

doc/tips-and-tricks.md

@@ -76,6 +76,10 @@ You can get PostgreSQL to stream very large result sets (when you are reducing o
 By default, PostgreSQL's JDBC driver does not always perform conversions from `java.util.Date` to a SQL data type.
 You can enable this by extending `SettableParameter` to the appropriate (Java) types, or by simply requiring [`next.jdbc.date-time`](https://cljdoc.org/d/seancorfield/next.jdbc/CURRENT/api/next.jdbc.date-time).
 
+In addition, if you want `java.time.Instant`, `java.time.LocalDate`, and `java.time.LocalDateTime` to be automatically converted to SQL data types, requiring `next.jdbc.date-time` will enable those as well (by extending `SettableParameter` for you).
+
+`next.jdbc.date-time` also includes functions that you can call at application startup to extend `ReadableColumn` to either return `java.time.Instant` or `java.time.LocalDate`/`java.time.LocalDateTime` (as well as a function to restore the default behavior of returning `java.sql.Date` and `java.sql.Timestamp`).
+
 ### Working with JSON and JSONB
 
 PostgreSQL has good support for [storing, querying and manipulating JSON data](https://www.postgresql.org/docs/current/datatype-json.html). Basic Clojure data structures (lists, vectors, and maps) transform pretty well to JSON data. With a little help `next.jdbc` can automatically convert Clojure data to JSON and back for us.

src/next/jdbc/date_time.clj

@@ -3,22 +3,25 @@
 (ns next.jdbc.date-time
   "Optional namespace that extends `next.jdbc.prepare/SettableParameter`
   to various date/time types so that they will all be treated as SQL
-  timestamps (which also supports date and time column types).
+  timestamps (which also supports date and time column types) and has
+  functions to extend `next.jdbc.result-set/ReadableColumn`.
 
   Simply requiring this namespace will extend the `SettableParameter` protocol
-  to the four types listed below. In addition, there are several `read-as-*`
-  functions here that will extend `next.jdbc.result-set/ReadableColumn` to
-  allow `java.sql.Date` and `java.sql.Timestamp` columns to be read as
-  (converted to) various Java Time types automatically. The expectation is
-  that you will call at most one of these, at application startup, to enable
-  the behavior you want.
+  to the four types listed below.
 
+  In addition, there are several `read-as-*` functions here that will
+  extend `next.jdbc.result-set/ReadableColumn` to allow `java.sql.Date`
+  and `java.sql.Timestamp` columns to be read as (converted to) various
+  Java Time types automatically. The expectation is that you will call at
+  most one of these, at application startup, to enable the behavior you want.
+
+  Database support for Java Time:
   * H2 and SQLite support conversion of Java Time (`Instant`, `LocalDate`,
     `LocalDateTime`) out of the box,
   * Nearly all databases support conversion of `java.util.Date` out of
     the box -- except PostgreSQL apparently!
 
-  Types supported:
+  Types supported by this namespace:
   * `java.time.Instant`
   * `java.time.LocalDate`
   * `java.time.LocalDateTime`

src/next/jdbc/result_set.clj

@@ -12,7 +12,11 @@
   A broad range of result set builder implementation functions are provided.
 
   Also provides the default implemenations for `Executable` and
-  the default `datafy`/`nav` behavior for rows from a result set."
+  the default `datafy`/`nav` behavior for rows from a result set.
+
+  See also https://cljdoc.org/d/seancorfield/next.jdbc/CURRENT/api/next.jdbc.date-time
+  for implementations of `ReadableColumn` that provide automatic
+  conversion of some SQL data types to Java Time objects."
   (:require [clojure.core.protocols :as core-p]
             [next.jdbc.prepare :as prepare]
             [next.jdbc.protocols :as p])