Documentation improvements (#107)

Closes #89

README.md

@@ -4,14 +4,14 @@
 
 Common db api for crystal. You will need to have a specific driver to access a database.
 
-* [sqlite](https://github.com/crystal-lang/crystal-sqlite3)
+* [SQLite](https://github.com/crystal-lang/crystal-sqlite3)
-* [mysql](https://github.com/crystal-lang/crystal-mysql)
+* [MySQL](https://github.com/crystal-lang/crystal-mysql)
-* [postgres](https://github.com/will/crystal-pg)
+* [PostgreSQL](https://github.com/will/crystal-pg)
-* [cassandra](https://github.com/kaukas/crystal-cassandra)
+* [Cassandra](https://github.com/kaukas/crystal-cassandra)
 
 ## Installation
 
-Add this to your application's `shard.yml`:
+If you are creating a shard that will work with _any_ driver, then add `crystal-db` as a dependency in `shard.yml`:
 
 ```yaml
 dependencies:
@@ -19,6 +19,18 @@ dependencies:
     github: crystal-lang/crystal-db
 ```
 
+If you are creating an application that will work with _some specific_ driver(s), then add them in `shard.yml`:
+
+```yaml
+dependencies:
+  sqlite3:
+    github: crystal-lang/crystal-sqlite3
+```
+
+`crystal-db` itself will be a nested dependency if drivers are included.
+
+Note: Multiple drivers can be included in the same application.
+
 ## Documentation
 
 * [Latest API](http://crystal-lang.github.io/crystal-db/api/latest/)
@@ -26,7 +38,9 @@ dependencies:
 
 ## Usage
 
-Since this is an abstract db api, its usage is through a concrete database driver.
+This shard only provides an abstract database API. In order to use it, a specific driver for the intended database has to be required as well:
+
+The following example uses SQLite where `?` indicates the arguments. If PostgreSQL is used `$1`, `$2`, etc. should be used. `crystal-db` does not interpret the statements.
 
 ```crystal
 require "db"
@@ -60,13 +74,14 @@ end
 
 ## Roadmap
 
-Issues not yet addressed
+Issues not yet addressed:
 
 - [x] Support non prepared statements. [#25](https://github.com/crystal-lang/crystal-db/pull/25)
 - [x] Time data type. (implementation details depends on actual drivers)
 - [x] Data type extensibility. Allow each driver to extend the data types allowed.
 - [x] Transactions & nested transactions. [#27](https://github.com/crystal-lang/crystal-db/pull/27)
 - [x] Connection pool.
+- [ ] Logging
 - [ ] Direct access to `IO` to avoid memory allocation for blobs.
 
 ## Contributing

src/db.cr

@@ -1,16 +1,22 @@
 require "uri"
 
-# The DB module is a unified interface to database access.
+# The DB module is a unified interface for database access.
-# Database dialects is supported by custom database driver shards.
+# Individual database systems are supported by specific database driver shards.
-# Check [crystal-lang/crystal-sqlite3](https://github.com/crystal-lang/crystal-sqlite3) for example.
 #
-# Drivers implementors check `Driver` class.
+# Available drivers include:
+# * [crystal-lang/crystal-sqlite3](https://github.com/crystal-lang/crystal-sqlite3) for SQLite
+# * [crystal-lang/crystal-mysql](https://github.com/crystal-lang/crystal-mysql) for MySQL and MariaDB
+# * [will/crystal-pg](https://github.com/will/crystal-pg) for PostgreSQL
+# * [kaukas/crystal-cassandra](https://github.com/kaukas/crystal-cassandra) for Cassandra
 #
-# DB manage a connection pool. The connection pool can be configured by `URI` query. See `Database`.
+# For basic instructions on implementing a new database driver, check `Driver` and the existing drivers.
+#
+# DB manages a connection pool. The connection pool can be configured by query parameters to the
+# connection `URI` as described in `Database`.
 #
 # ### Usage
 #
-# Assuming `crystal-sqlite3` is included a sqlite3 database can be opened with `#open`.
+# Assuming `crystal-sqlite3` is included a SQLite3 database can be opened with `#open`.
 #
 # ```
 # db = DB.open "sqlite3:./path/to/db/file.db"
@@ -36,11 +42,14 @@ require "uri"
 #
 # Check a full working version:
 #
+# The following example uses SQLite where `?` indicates the arguments. If PostgreSQL is used `$1`, `$2`, etc. should be used. `crystal-db` does not interpret the statements.
+#
 # ```
 # require "db"
 # require "sqlite3"
 #
 # DB.open "sqlite3:./file.db" do |db|
+#   # When using the pg driver, use $1, $2, etc. instead of ?
 #   db.exec "create table contacts (name text, age integer)"
 #   db.exec "insert into contacts values (?, ?)", "John Doe", 30
 #
@@ -95,15 +104,19 @@ module DB
     @@drivers ||= {} of String => Driver.class
   end
 
-  # Opens a database using the specified *uri*.
+  # Creates a `Database` pool and opens initial connection(s) as specified in the connection *uri*.
+  # Use `DB#connect` to open a single connection.
+  #
   # The scheme of the *uri* determines the driver to use.
-  # Returned database must be closed by `Database#close`.
+  # Connection parameters such as hostname, user, database name, etc. are specified according
-  # If a block is used the database is yielded and closed automatically.
+  # to each database driver's specific format.
+  #
+  # The returned database must be closed by `Database#close`.
   def self.open(uri : URI | String)
     build_database(uri)
   end
 
-  # Same as `#open` but the database is yielded and closed automatically.
+  # Same as `#open` but the database is yielded and closed automatically at the end of the block.
   def self.open(uri : URI | String, &block)
     db = build_database(uri)
     begin

src/db/database.cr

@@ -4,23 +4,29 @@ require "weak_ref"
 module DB
   # Acts as an entry point for database access.
   # Connections are managed by a pool.
-  # The connection pool can be configured from URI parameters:
+  # Use `DB#open` to create a `Database` instance.
-  #
-  #   - initial_pool_size (default 1)
-  #   - max_pool_size (default 0 = unlimited)
-  #   - max_idle_pool_size (default 1)
-  #   - checkout_timeout (default 5.0)
-  #   - retry_attempts (default 1)
-  #   - retry_delay (in seconds, default 1.0)
-  #
-  # When querying a database prepared statements are used by default.
-  # This can be changed from the `prepared_statements` URI parameter:
-  #
-  #   - prepared_statements = `true`|`false` (default `true`)
-  #
-  # It should be created from DB module. See `DB#open`.
   #
   # Refer to `QueryMethods` and `SessionMethods` for documentation about querying the database.
+  #
+  # ## Database URI
+  #
+  # Connection parameters are configured in a URI. The format is specified by the individual
+  # database drivers. See the [reference book](https://crystal-lang.org/reference/database/) for examples.
+  #
+  # The connection pool can be configured from URI parameters:
+  #
+  #   - `initial_pool_size` (default 1)
+  #   - `max_pool_size` (default 0 = unlimited)
+  #   - `max_idle_pool_size` (default 1)
+  #   - `checkout_timeout` (default 5.0)
+  #   - `retry_attempts` (default 1)
+  #   - `retry_delay` (in seconds, default 1.0)
+  #
+  # When querying a database, prepared statements are used by default.
+  # This can be changed from the `prepared_statements` URI parameter:
+  #
+  #   - `prepared_statements` (true, or false, default true)
+  #
   class Database
     include SessionMethods(Database, PoolStatement)
     include ConnectionContext