The big doc update. Also cleaned up a bunch of imports and little things

I saw while documenting.

Author: schveiguy

SAFE_MIGRATION.md

@@ -1,6 +1,9 @@
 #!/bin/sh
-rdmd --build-only -c -Isource -Dddocs_tmp -X -Xfdocs/docs.json -version=MySQLDocs --force source/mysql/package.d
-rm -rf docs_tmp
+# Need taggedalgebraic
+rm -rf ta
+git clone https://github.com/s-ludwig/taggedalgebraic.git ta
+rdmd --build-only -c -Isource -Ita/source -Dddocs_tmp -X -Xfdocs/docs.json -version=MySQLDocs --force source/mysql/package.d
+rm -rf docs_tmp ta
 rm source/mysql/package.o
 
 dub --version

build-docs

@@ -6,9 +6,10 @@ Macros:
 	DOLLAR = $
 	COLON = :
 	EM       = $(B $(I $0) )
-	
+
 	TYPE_MAPPINGS = See the $(LINK2 $(DDOX_ROOT_DIR)/mysql.html, MySQL/D Type Mappings tables)
-	
+	SAFE_MIGRATION = See the $(LINK2 https://github.com/mysql-d/mysql-native/blob/master/SAFE_MIGRATION.md, Safe Migration) document for more details.
+
 	STD_DATETIME_DATE = $(D_INLINECODE $(LINK2 https://dlang.org/phobos/std_datetime_date.html#$0, $0))
 	STD_EXCEPTION     = $(D_INLINECODE $(LINK2 https://dlang.org/phobos/std_exception.html#$0, $0))
 	STD_FILE          = $(D_INLINECODE $(LINK2 https://dlang.org/phobos/std_file.html#$0, $0))

ddoc/macros.ddoc

@@ -1,13 +1,15 @@
 /++
-This module imports `mysql.unsafe.commands`, which provides the Variant-based
-interface to mysql. In the future, this will switch to importing the
+This module publicly imports `mysql.unsafe.commands`, which provides the
+Variant-based interface to mysql. In the future, this will switch to importing the
 `mysql.safe.commands`, which provides the @safe interface to mysql. Please see
 those two modules for documentation on the functions provided. It is highly
 recommended to import `mysql.safe.commands` and not the unsafe commands, as
 that is the future for mysql-native.
 
 In the far future, the unsafe version will be deprecated and removed, and the
 safe version moved to this location.
+
+$(SAFE_MIGRATION)
 +/
 module mysql.commands;
 public import mysql.unsafe.commands;

source/mysql/commands.d

@@ -1,3 +1,21 @@
+/++
+This module publicly imports `mysql.unsafe.connection`, which provides
+backwards compatible functions for connecting to a MySQL/MariaDB server.
+
+It is recommended instead to import `mysql.safe.connection`, which provides
+@safe-only mechanisms to connect to a database.
+
+Note that the common pieces of the connection are documented and currently
+reside in `mysql.impl.connection`. The safe and unsafe portions of the API
+reside in `mysql.unsafe.connection` and `mysql.safe.connection` respectively.
+Please see these modules for information on using a MySQL `Connection` object.
+
+In the future, this will migrate to importing `mysql.safe.connection`. In the
+far future, the unsafe version will be deprecated and removed, and the safe
+version moved to this location.
+
+$(SAFE_MIGRATION)
++/
 module mysql.connection;
 
 public import mysql.unsafe.connection;

source/mysql/connection.d

@@ -40,6 +40,9 @@ properly escaped all using the buffer that formattedWrite provides.
 
 Params:
 	Input = (Template Param) Type of the input
+
+Note:
+    The delegate is expected to be @safe as of version 3.1.0.
 +/
 struct MysqlEscape ( Input )
 {
@@ -65,7 +68,7 @@ MysqlEscape!(T) mysqlEscape ( T ) ( T input )
 
 @("mysqlEscape")
 debug(MYSQLN_TESTS)
-unittest
+@safe unittest
 {
 	import std.array : appender;
 

source/mysql/escape.d

@@ -1,5 +1,15 @@
-/// Connect to a MySQL/MariaDB server.
-module mysql.internal.connection;
+/++
+Connect to a MySQL/MariaDB server.
+
+WARNING:
+This module is used to consolidate the common implementation of the safe and
+unafe API. DO NOT directly import this module, please import one of
+`mysql.connection`, `mysql.safe.connection`, or `mysql.unsafe.connection`. This
+module will be removed in a future version without deprecation.
+
+$(SAFE_MIGRATION)
++/
+module mysql.impl.connection;
 
 import std.algorithm;
 import std.conv;
@@ -14,8 +24,8 @@ import mysql.protocol.comms;
 import mysql.protocol.constants;
 import mysql.protocol.packets;
 import mysql.protocol.sockets;
-import mysql.internal.result;
-import mysql.internal.prepared;
+import mysql.impl.result;
+import mysql.impl.prepared;
 import mysql.types;
 
 @safe:

source/mysql/internal/connection.d renamed to source/mysql/impl/connection.d

@@ -8,13 +8,21 @@ If you don't want to, refer to `mysql.connection.Connection`.
 This provides various benefits over creating a new connection manually,
 such as automatically reusing old connections, and automatic cleanup (no need to close
 the connection when done).
+
+WARNING:
+This module is used to consolidate the common implementation of the safe and
+unafe API. DO NOT directly import this module, please import one of
+`mysql.pool`, `mysql.safe.pool`, or `mysql.unsafe.pool`. This module will be
+removed in a future version without deprecation.
+
+$(SAFE_MIGRATION)
 +/
-module mysql.internal.pool;
+module mysql.impl.pool;
 
 import std.conv;
 import std.typecons;
-import mysql.connection;
-import mysql.prepared;
+import mysql.impl.connection;
+import mysql.impl.prepared;
 import mysql.protocol.constants;
 debug(MYSQLN_TESTS)
 {
@@ -86,8 +94,14 @@ version(IncludeMySQLPool)
 
 	If, for any reason, this class doesn't suit your needs, it's easy to just
 	use vibe.d's $(LINK2 http://vibed.org/api/vibe.core.connectionpool/ConnectionPool, ConnectionPool)
-	directly. Simply provide it with a delegate that creates a new `mysql.connection.Connection`
-	and does any other custom processing if needed.
+	directly. Simply provide it with a delegate that creates a new
+	`mysql.impl.connection.Connection` and does any other custom processing if
+	needed.
+
+	You should not use this template directly, but rather import
+	`mysql.safe.pool` or `mysql.unsafe.pool` or `mysql.pool`, which will alias
+	MySQLPool to the correct instantiation. The boolean parameter here
+	specifies whether the pool is operating in safe mode or unsafe mode.
 	+/
 	class MySQLPoolImpl(bool isSafe)
 	{
@@ -198,7 +212,7 @@ version(IncludeMySQLPool)
 				return lockConnectionImpl();
 			}
 
-		// the implementation we want to imply attributes
+		// the implementation we want to infer attributes
 		private final lockConnectionImpl()
 		{
 			auto conn = m_pool.lockConnection();
@@ -376,7 +390,7 @@ version(IncludeMySQLPool)
 
 		/// Is the given statement set to be automatically registered on all
 		/// connections obtained from this connection pool?
-		bool isAutoRegistered(Prepared prepared) @safe
+		bool isAutoRegistered(SafePrepared prepared) @safe
 		{
 			return isAutoRegistered(prepared.sql);
 		}
@@ -393,7 +407,7 @@ version(IncludeMySQLPool)
 
 		/// Is the given statement set to be automatically released on all
 		/// connections obtained from this connection pool?
-		bool isAutoReleased(Prepared prepared) @safe
+		bool isAutoReleased(SafePrepared prepared) @safe
 		{
 			return isAutoReleased(prepared.sql);
 		}
@@ -415,7 +429,7 @@ version(IncludeMySQLPool)
 
 		Equivalent to `!isAutoRegistered && !isAutoReleased`.
 		+/
-		bool isAutoCleared(Prepared prepared) @safe
+		bool isAutoCleared(SafePrepared prepared) @safe
 		{
 			return isAutoCleared(prepared.sql);
 		}
@@ -490,9 +504,15 @@ version(IncludeMySQLPool)
 		static void doit(bool isSafe)()
 		{
 			static if(isSafe)
+			{
 				import mysql.safe.commands;
+				import mysql.safe.connection;
+			}
 			else
+			{
 				import mysql.unsafe.commands;
+				import mysql.unsafe.connection;
+			}
 			alias MySQLPool = MySQLPoolImpl!isSafe;
 			auto pool = new MySQLPool(testConnectionStr);