update docs

src/db/db.cr

@@ -14,18 +14,20 @@ require "uri"
 # Assuming `crystal-sqlite3` is included a sqlite3 database can be opened with `#open`.
 #
 # ```
-# db = DB.open "sqlite3:%3Amemory%3A" # or sqlite3:./path/to/db/file.db
+# db = DB.open "sqlite3:./path/to/db/file.db"
 # db.close
 # ```
 #
 # If a block is given to `#open` the database is closed automatically
 #
 # ```
-# DB.open "sqlite3:%3Amemory%3A" do |db|
+# DB.open "sqlite3:./file.db" do |db|
 #   # work with db
 # end # db is closed
 # ```
 #
+# In the code above `db` is a `Database`. Methods available for querying it are described in `QueryMethods`.
+#
 # Three kind of statements can be performed:
 # 1. `Database#exec` waits no response from the database.
 # 2. `Database#scalar` reads a single value of the response.
@@ -39,7 +41,7 @@ require "uri"
 # require "db"
 # require "sqlite3"
 #
-# DB.open "sqlite3://%3Amemory%3A" do |db|
+# DB.open "sqlite3:./file.db" do |db|
 #   db.exec "create table contacts (name string, age integer)"
 #   db.exec "insert into contacts values (?, ?)", "John Doe", 30
 #

src/db/query_methods.cr

@@ -15,8 +15,10 @@ module DB
   #
   # Convention of mapping how arguments are mapped to the query depends on each driver.
   #
-  # Including `QueryMethods` requires a `prepare(query) : Statement` method.
+  # Including `QueryMethods` requires a `prepare(query) : Statement` method that is not expected
+  # to be called directly.
   module QueryMethods
+    # :nodoc:
     abstract def prepare(query) : Statement
 
     # Returns a `ResultSet` for the `query`.