Improve protocol documentation

src/next/jdbc/prepare.clj

@@ -5,7 +5,10 @@
   created by the next generation java.jdbc library.
 
   set-parameters is public and may be useful if you have a PreparedStatement
-  that you wish to reuse and (re)set the parameters on it."
+  that you wish to reuse and (re)set the parameters on it.
+
+  Defines the SettableParameter protocol for converting Clojure values
+  to database-specific values."
   (:require [next.jdbc.protocols :as p])
   (:import (java.sql Connection
                      PreparedStatement

src/next/jdbc/protocols.clj

@@ -3,15 +3,18 @@
 (ns next.jdbc.protocols
   "This is the extensible core of the next generation java.jdbc library.
 
+  Sourceable protocol:
   get-datasource -- turn something into a javax.sql.DataSource; implementations
       are provided for strings, hash maps (db-spec structures), and also a
       DataSource (which just returns itself).
 
+  Connectable protocol:
   get-connection -- create a new JDBC connection that should be closed when you
       are finished with it; implementations are provided for DataSource and
       Object, on the assumption that an Object can possibly be turned into a
       DataSource.
 
+  Executable protocol:
   -execute -- given SQL and parameters, produce a 'reducible' that, when
       reduced, executes the SQL and produces a ResultSet that can be processed;
       implementations are provided for Connection, DataSource,
@@ -31,10 +34,12 @@
       PreparedStatement, and Object (on the assumption that an Object can be
       turned into a DataSource and therefore used to get a Connection).
 
+  Preparable protocol:
   prepare -- given SQL and parameters, produce a PreparedStatement that can
       be executed (by -execute above); implementation is provided for
       Connection.
 
+  Transactable protocol:
   -transact -- given a function (presumably containing SQL operations),
       run the function inside a SQL transaction; implementations are provided
       for Connection, DataSource, and Object (on the assumption that an Object

src/next/jdbc/result_set.clj

@@ -1,7 +1,16 @@
 ;; copyright (c) 2018-2019 Sean Corfield, all rights reserved
 
 (ns next.jdbc.result-set
-  "An implementation of ResultSet handling functions."
+  "An implementation of ResultSet handling functions.
+
+  Defines the following protocols:
+  * ReadableColumn -- to read column values by label or index
+  * RowBuilder -- for materializing a row
+  * ResultSetBuilder -- for materializing a result set
+  * DatafiableRow -- for turning a row into something datafiable
+
+  Also provides the default implemenations for Executable and
+  the default datafy/nav behavior for rows from a result set."
   (:require [clojure.core.protocols :as core-p]
             [next.jdbc.prepare :as prepare]
             [next.jdbc.protocols :as p])
@@ -11,7 +20,7 @@
 
 (set! *warn-on-reflection* true)
 
-(defn- get-column-names
+(defn get-column-names
   "Given ResultSetMetaData, return a vector of columns names, each qualified by
   the table from which it came.