From 25f0291588e0172e3dba5200234f39dc68deee96 Mon Sep 17 00:00:00 2001
From: Erik Smith <erik@cruiserhouse.com>
Date: Sat, 24 Feb 2018 09:52:18 -0800
Subject: [PATCH] start of simple inline docs

---
 src/std/database/{front.d => BasicDatabase.d} | 60 +++++++++++++++----
 src/std/database/freetds/database.d           |  2 +-
 src/std/database/mysql/database.d             |  2 +-
 src/std/database/odbc/database.d              |  2 +-
 src/std/database/oracle/database.d            |  2 +-
 src/std/database/poly/database.d              |  2 +-
 src/std/database/postgres/database.d          |  2 +-
 src/std/database/rowset.d                     |  2 +-
 src/std/database/sqlite/database.d            |  2 +-
 src/std/database/testsuite.d                  |  2 +-
 10 files changed, 59 insertions(+), 19 deletions(-)
 rename src/std/database/{front.d => BasicDatabase.d} (93%)

diff --git a/src/std/database/front.d b/src/std/database/BasicDatabase.d
similarity index 93%
rename from src/std/database/front.d
rename to src/std/database/BasicDatabase.d
index ca72e6c..28a28b9 100644
--- a/src/std/database/front.d
+++ b/src/std/database/BasicDatabase.d
@@ -1,4 +1,4 @@
-module std.database.front;
+module std.database.BasicDatabase;
 import std.experimental.logger;
 import std.database.exception;
 import std.datetime;
@@ -17,19 +17,33 @@ import std.variant;
 import std.range.primitives;
 import std.database.option;
 
-public import std.database.array;
+/**
+  BasicDatabase:  a common and generic front-end for database access
+
+  Typically, this interface is impliclity used when import a specific database
+  driver as shown in this simple example:
+
+  ---
+  import std.database.sqlite;
+  auto db = createDatabase("file:///testdb");
+  auto rows = db.connection.query("select name,score from score").rows;
+  foreach (r; rows) {
+    writeln(r[0].as!string,",",r[1].as!int);
+  }
+  ---
 
-/*
-   require a specific minimum version of DMD (2.071)
-   can't use yet because DMD is reporting wrong version
+  For advanced usage, you can also explicitly instantiate a BasicDatabase
+  with a driver:
+  ---
+  import std.database;
+  alias DB = BasicDatabase!(MyDriver!MyPolicy, MyPolicy);
+  ---
 
-   import std.compiler;
-   static assert(
-   name != "Digital Mars D" ||
-   (version_major == 2 && version_minor == 70));
- */
+*/
 
 
+public import std.database.array;
+
 enum ValueType {
     Int,
     String,
@@ -53,6 +67,10 @@ enum Feature {
 
 alias FeatureArray = Feature[];
 
+/**
+  A root type for interacting with databases. It's primary purpose is act as
+  a factory for database connections. This type can be shared across threads.
+*/
 struct BasicDatabase(D,P) {
     alias Driver = D;
     alias Policy = P;
@@ -125,6 +143,9 @@ auto ref driverDatabase() {return data_.database;}
     }
 }
 
+/**
+  Holds a connection to the database.
+*/
 struct BasicConnection(D,P) {
     alias Driver = D;
     alias Policy = P;
@@ -205,6 +226,9 @@ data_ = Data(&db.data_.refCountedPayload(),uri);
 
 }
 
+/**
+  Manages statement details such as query execution and input binding.
+*/
 struct BasicStatement(D,P) {
     alias Driver = D;
     alias Policy = P;
@@ -314,6 +338,10 @@ struct BasicStatement(D,P) {
 }
 
 
+/**
+  An internal class for result access and iteration. See the RowSet type for range based access
+  to results
+*/
 struct BasicResult(D,P) {
     alias Driver = D;
     alias Policy = P;
@@ -371,6 +399,9 @@ package:
     }
 }
 
+/**
+  A range over result column information
+*/
 struct BasicColumnSet(D,P) {
     alias Driver = D;
     alias Policy = P;
@@ -415,6 +446,9 @@ struct BasicColumn(D,P) {
 }
 
 
+/**
+  A input range over the results of a query.
+*/
 struct BasicRowSet(D,P) {
     alias Driver = D;
     alias Policy = P;
@@ -485,6 +519,9 @@ struct BasicRowSet(D,P) {
     void popFront() {result_.next();}
 }
 
+/**
+  A row accessor for the current row in a RowSet input range.
+*/
 struct BasicRow(D,P) {
     alias Driver = D;
     alias Policy = P;
@@ -524,6 +561,9 @@ struct BasicRow(D,P) {
 }
 
 
+/**
+  A value accessor for an indexed value in the current row in a RowSet input range.
+*/
 struct BasicValue(D,P) {
     alias Driver = D;
     alias Policy = P;
diff --git a/src/std/database/freetds/database.d b/src/std/database/freetds/database.d
index 5840231..f0a11ef 100644
--- a/src/std/database/freetds/database.d
+++ b/src/std/database/freetds/database.d
@@ -14,7 +14,7 @@ import std.typecons;
 import std.container.array;
 import std.experimental.logger;
 public import std.database.allocator;
-import std.database.front;
+import std.database.BasicDatabase;
 import std.datetime;
 
 struct DefaultPolicy {
diff --git a/src/std/database/mysql/database.d b/src/std/database/mysql/database.d
index 7bccf4a..6ad28f0 100644
--- a/src/std/database/mysql/database.d
+++ b/src/std/database/mysql/database.d
@@ -20,7 +20,7 @@ version(Windows) {
 import std.database.mysql.bindings;
 import std.database.exception;
 import std.database.allocator;
-import std.database.front;
+import std.database.BasicDatabase;
 import std.container.array;
 import std.experimental.logger;
 import std.string;
diff --git a/src/std/database/odbc/database.d b/src/std/database/odbc/database.d
index f6e6dd9..bad78c0 100644
--- a/src/std/database/odbc/database.d
+++ b/src/std/database/odbc/database.d
@@ -16,7 +16,7 @@ import std.typecons;
 import std.container.array;
 import std.experimental.logger;
 public import std.database.allocator;
-import std.database.front;
+import std.database.BasicDatabase;
 import std.datetime;
 
 //alias long SQLLEN;
diff --git a/src/std/database/oracle/database.d b/src/std/database/oracle/database.d
index 98b90ba..5d32621 100644
--- a/src/std/database/oracle/database.d
+++ b/src/std/database/oracle/database.d
@@ -16,7 +16,7 @@ import std.container.array;
 
 import std.datetime;
 
-import std.database.front;
+import std.database.BasicDatabase;
 
 struct DefaultPolicy {
     alias Allocator = MyMallocator;
diff --git a/src/std/database/poly/database.d b/src/std/database/poly/database.d
index b4f2ff7..cb51d5d 100644
--- a/src/std/database/poly/database.d
+++ b/src/std/database/poly/database.d
@@ -10,7 +10,7 @@ public import std.database.exception;
 import std.stdio;
 import std.typecons;
 import std.container.array;
-import std.database.front;
+import std.database.BasicDatabase;
 import std.database.allocator;
 import std.database.source;
 import std.database.common;
diff --git a/src/std/database/postgres/database.d b/src/std/database/postgres/database.d
index fb038f3..7972dfe 100644
--- a/src/std/database/postgres/database.d
+++ b/src/std/database/postgres/database.d
@@ -12,7 +12,7 @@ import std.database.source;
 import std.database.allocator;
 import std.container.array;
 import std.experimental.logger;
-import std.database.front;
+import std.database.BasicDatabase;
 
 import std.stdio;
 import std.typecons;
diff --git a/src/std/database/rowset.d b/src/std/database/rowset.d
index b376302..19c4a35 100644
--- a/src/std/database/rowset.d
+++ b/src/std/database/rowset.d
@@ -1,5 +1,5 @@
 module std.database.rowset;
-import std.database.front;
+import std.database.BasicDatabase;
 import std.datetime;
 import std.container.array;
 
diff --git a/src/std/database/sqlite/database.d b/src/std/database/sqlite/database.d
index 63106a7..179fc53 100644
--- a/src/std/database/sqlite/database.d
+++ b/src/std/database/sqlite/database.d
@@ -13,7 +13,7 @@ import std.database.source;
 import std.database.allocator;
 import std.database.pool;
 import std.experimental.logger;
-import std.database.front;
+import std.database.BasicDatabase;
 
 import std.container.array;
 import std.datetime;
diff --git a/src/std/database/testsuite.d b/src/std/database/testsuite.d
index a89fee9..91af569 100644
--- a/src/std/database/testsuite.d
+++ b/src/std/database/testsuite.d
@@ -5,7 +5,7 @@ import std.stdio;
 import std.experimental.logger;
 import std.datetime;
 
-import std.database.front: Feature;
+import std.database.BasicDatabase: Feature;
 
 void testAll(Database) (string source) {