Now builds docs (with latest version of compiler if gen-package-version

schveiguy · schveiguy · commit f7000919a283 · 2020-04-19T14:44:17.000-04:00
is updated)
diff --git a/.gitignore b/.gitignore
@@ -10,6 +10,7 @@
 
 /docs/docs.json
 /docs/public/mysql/
+/docs/public/taggedalgebraic/
 /docs/public/file_hashes.json
 /docs/public/index.html
 /docs/public/mysql.html
diff --git a/build-docs b/build-docs
@@ -16,12 +16,18 @@ rm -rf docs_tmp ta
 rm source/mysql/package.o
 
 dub --version
-dub run gen-package-version -- mysql --ddoc=ddoc --src=source
+if ! dub run gen-package-version -- mysql --ddoc=ddoc --src=source; then
+  echo "Failed to build gen-package-version"
+  exit 1
+fi
 rm source/mysql/packageVersion.d
 
 echo Building ddox...
 cd ./ddox
-dub build
+if ! dub build; then
+   echo "Failed to build ddox"
+   exit 1
+fi
 cd ..
 echo Done building ddox...
 
diff --git a/examples/homePage/dub.selections.json b/examples/homePage/dub.selections.json
@@ -6,6 +6,7 @@
 		"libev": "5.0.0+4.04",
 		"libevent": "2.0.1+2.0.16",
 		"memutils": "0.4.13",
+		"mysql-native": {"path":"../.."},
 		"openssl": "1.1.4+1.0.1g",
 		"stdx-allocator": "2.77.5",
 		"taggedalgebraic": "0.11.8",
diff --git a/source/mysql/commands.d b/source/mysql/commands.d
@@ -1,10 +1,5 @@
 /++
-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.
+This module publicly imports `mysql.unsafe.commands`. Please see that module for more documentation.
 
 In the far future, the unsafe version will be deprecated and removed, and the
 safe version moved to this location.
diff --git a/source/mysql/connection.d b/source/mysql/connection.d
@@ -1,14 +1,6 @@
 /++
-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.
+This module publicly imports `mysql.unsafe.connection`. Please see that module
+for more documentation.
 
 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
diff --git a/source/mysql/impl/connection.d b/source/mysql/impl/connection.d
@@ -1,5 +1,5 @@
 /++
-Connect to a MySQL/MariaDB server.
+Implementation - Connection class.
 
 WARNING:
 This module is used to consolidate the common implementation of the safe and
@@ -1132,15 +1132,15 @@ unittest
 	cn.exec("DROP TABLE `dropConnection`");
 }
 
-/+
+/*
 Test Prepared's ability to be safely refcount-released during a GC cycle
 (ie, `Connection.release` must not allocate GC memory).
 
 Currently disabled because it's not guaranteed to always work
 (and apparently, cannot be made to work?)
 For relevant discussion, see issue #159:
 https://github.com/mysql-d/mysql-native/issues/159
-+/
+*/
 version(none)
 debug(MYSQLN_TESTS)
 {
diff --git a/source/mysql/impl/pool.d b/source/mysql/impl/pool.d
@@ -1,4 +1,6 @@
 /++
+Implementation - Vibe.d MySQL Pool.
+
 Connect to a MySQL/MariaDB database using vibe.d's
 $(LINK2 http://vibed.org/api/vibe.core.connectionpool/ConnectionPool, ConnectionPool).
 
diff --git a/source/mysql/impl/prepared.d b/source/mysql/impl/prepared.d
@@ -1,5 +1,5 @@
 /++
-Use a DB via SQL prepared statements.
+Implementation - Prepared statements.
 
 WARNING:
 This module is used to consolidate the common implementation of the safe and
diff --git a/source/mysql/impl/result.d b/source/mysql/impl/result.d
@@ -1,5 +1,5 @@
 /++
-Structures for data received: rows and result sets (ie, a range of rows).
+Implementation - Data result structures.
 
 WARNING:
 This module is used to consolidate the common implementation of the safe and
diff --git a/source/mysql/package.d b/source/mysql/package.d
@@ -75,6 +75,20 @@ module mysql;
 // by default we do the unsafe API.
 public import mysql.unsafe;
 
+// import the safe version for generating documentation.
+version(MySQLDocs)
+{
+	// also document safe items
+	import mysql.safe;
+
+	// also document forwarding modules
+	import mysql.commands;
+	import mysql.result;
+	import mysql.pool;
+	import mysql.prepared;
+	import mysql.connection;
+}
+
 debug(MYSQLN_TESTS)      version = DoCoreTests;
 debug(MYSQLN_CORE_TESTS) version = DoCoreTests;
 
diff --git a/source/mysql/pool.d b/source/mysql/pool.d
@@ -1,9 +1,5 @@
 /++
-This module publicly imports `mysql.unsafe.pool`, which provides backwards
-compatible functions for using vibe.d's
-$(LINK2 http://vibed.org/api/vibe.core.connectionpool/ConnectionPool, ConnectionPool).
-
-Please see the module documentation in `mysql.impl.pool` for more details.
+This module publicly imports `mysql.unsafe.pool`. Please see that module for more documentation.
 
 In the future, this will migrate to importing `mysql.safe.pool`. In the far
 future, the unsafe version will be deprecated and removed, and the safe version
diff --git a/source/mysql/result.d b/source/mysql/result.d
@@ -1,12 +1,6 @@
 /++
-This module publicly imports `mysql.unsafe.result`, which provides backwards
-compatible structures for processing rows of data from a MySQL server. Please
-see that module for details on usage.
-
-It is recommended instead ot import `mysql.safe.result`, which provides
-@safe-only mechanisms for processing rows of data.
-
-Note that the actual structs are documented in `mysql.impl.result`.
+This module publicly imports `mysql.unsafe.result`. Please see that module for
+more documentation.
 
 In the future, this will migrate to importing `mysql.safe.result`. In the far
 future, the unsafe version will be deprecated and removed, and the safe version
diff --git a/source/mysql/safe/commands.d b/source/mysql/safe/commands.d
@@ -1,4 +1,6 @@
 /++
+Use a DB via plain SQL statements (safe version).
+
 Commands that are expected to return a result set - queries - have distinctive
 methods that are enforced. That is it will be an error to call such a method
 with an SQL command that does not produce a result set. So for commands like
diff --git a/source/mysql/safe/connection.d b/source/mysql/safe/connection.d
@@ -1,8 +1,12 @@
 /++
-Connect to a MySQL/MariaDB server.
+Connect to a MySQL/MariaDB server (safe version).
 
 This is the @safe API for the Connection type. It publicly imports `mysql.impl.connection`, and also provides the safe version of the API for preparing statements.
 
+Note that the common pieces of the connection are documented and currently
+reside in `mysql.impl.connection`. Please see this module for documentation of
+the connection object.
+
 $(SAFE_MIGRATION)
 +/
 module mysql.safe.connection;
@@ -18,9 +22,10 @@ import mysql.safe.commands;
 Submit an SQL command to the server to be compiled into a prepared statement.
 
 This will automatically register the prepared statement on the provided connection.
-The resulting `mysql.impl.prepared.SafePrepared` can then be used freely on ANY `Connection`,
-as it will automatically be registered upon its first use on other connections.
-Or, pass it to `Connection.register` if you prefer eager registration.
+The resulting `mysql.impl.prepared.SafePrepared` can then be used freely on ANY
+`mysql.impl.connection.Connection`, as it will automatically be registered upon
+its first use on other connections. Or, pass it to
+`mysql.impl.connection.Connection.register` if you prefer eager registration.
 
 Internally, the result of a successful outcome will be a statement handle - an ID -
 for the prepared statement, a count of the parameters required for
diff --git a/source/mysql/safe/package.d b/source/mysql/safe/package.d
@@ -1,5 +1,5 @@
 /++
-Imports all of $(LINK2 https://github.com/mysql-d/mysql-native, mysql-native).
+Imports all of $(LINK2 https://github.com/mysql-d/mysql-native, mysql-native) (safe versions).
 
 This module will import all modules that use the safe API of the mysql library.
 In a future version, this will become the default.
diff --git a/source/mysql/safe/pool.d b/source/mysql/safe/pool.d
@@ -1,9 +1,9 @@
 /++
 Connect to a MySQL/MariaDB database using vibe.d's
-$(LINK2 http://vibed.org/api/vibe.core.connectionpool/ConnectionPool, ConnectionPool).
+$(LINK2 http://vibed.org/api/vibe.core.connectionpool/ConnectionPool, ConnectionPool) (safe version).
 
-This aliases `mysql.impl.pool.MySQLPoolImpl!true` as MySQLPool. Please see the
-`mysql.impl.pool` moddule for documentation on how to use MySQLPool.
+This aliases `mysql.impl.pool.MySQLPoolImpl!true` as `MySQLPool`. Please see the
+`mysql.impl.pool` moddule for documentation on how to use `MySQLPool`.
 
 This is the @safe version of mysql's pool module, and as such uses only @safe
 callback delegates. If you wish to use @system callbacks, import
diff --git a/source/mysql/safe/prepared.d b/source/mysql/safe/prepared.d
@@ -1,6 +1,6 @@
 /++
-This module publicly imports `mysql.impl.prepared`. See that module for
-documentation on using prepared statements with a MySQL server.
+This module publicly imports `mysql.impl.prepared` (safe version). See that
+module for documentation on using prepared statements with a MySQL server.
 
 This module also aliases the safe versions of structs to the original struct
 names to aid in transitioning to using safe code with minimal impact.
diff --git a/source/mysql/safe/result.d b/source/mysql/safe/result.d
@@ -1,5 +1,5 @@
 /++
-This module publicly imports `mysql.impl.result`. See that module for documentation on how to use result and result range structures.
+This module publicly imports `mysql.impl.result`. See that module for documentation on how to use result and result range structures (safe versions).
 
 This module also aliases the safe versions of these structs to the original
 struct names to aid in transitioning to using safe code with minimal impact.
diff --git a/source/mysql/unsafe/commands.d b/source/mysql/unsafe/commands.d
@@ -1,11 +1,15 @@
 /++
-Use a DB via plain SQL statements.
+Use a DB via plain SQL statements (unsafe version).
 
 Commands that are expected to return a result set - queries - have distinctive
 methods that are enforced. That is it will be an error to call such a method
 with an SQL command that does not produce a result set. So for commands like
 SELECT, use the `query` functions. For other commands, like
 INSERT/UPDATE/CREATE/etc, use `exec`.
+
+This is the @system version of mysql's command module, and as such uses the @system
+rows and result ranges, and the `Variant` type. For the `MySQLVal` safe
+version, please import `mysql.safe.commands`.
 +/
 
 module mysql.unsafe.commands;
@@ -130,6 +134,9 @@ unittest
 /++
 Execute an SQL command or prepared statement, such as INSERT/UPDATE/CREATE/etc.
 
+Note: The safe `mysql.safe.commands.exec` is also aliased here, so you have access to all
+those overloads in addition to these.
+
 This method is intended for commands such as which do not produce a result set
 (otherwise, use one of the `query` functions instead.) If the SQL command does
 produces a result set (such as SELECT), `mysql.exceptions.MYXResultRecieved`
@@ -171,8 +178,6 @@ auto myInt = 7;
 auto rowsAffected = myConnection.exec("INSERT INTO `myTable` (`a`) VALUES (?)", myInt);
 ---
 +/
-alias exec = SC.exec;
-///ditto
 ulong exec(Connection conn, const(char[]) sql, Variant[] args) @system
 {
 	auto prepared = conn.prepare(sql);
@@ -195,6 +200,10 @@ ulong exec(Connection conn, ref BackwardCompatPrepared prepared) @system
 	return result;
 }
 
+//ditto
+// Note: doesn't look right in ddox, so I removed this as a ditto.
+alias exec = SC.exec;
+
 
 /++
 Execute an SQL SELECT command or prepared statement.
diff --git a/source/mysql/unsafe/connection.d b/source/mysql/unsafe/connection.d
@@ -1,9 +1,14 @@
 /++
-Connect to a MySQL/MariaDB server.
+Connect to a MySQL/MariaDB server (unsafe version).
 
-This is the unsafe API for the Connection type. It publicly imports `mysql.impl.connection`, and also provides the unsafe version of the API for preparing statements.
+This is the unsafe API for the Connection type. It publicly imports
+`mysql.impl.connection`, and also provides the unsafe version of the API for
+preparing statements. Note that unsafe prepared statements actually use safe
+code underneath.
 
-Note that unsafe prepared statements are no different from safe prepared statements, except for the mechanism to set parameters allows Variant.
+Note that the common pieces of the connection are documented and currently
+reside in `mysql.impl.connection`. Please see this module for documentation of
+the connection object.
 
 This module also contains the soon-to-be-deprecated BackwardCompatPrepared type.
 
diff --git a/source/mysql/unsafe/package.d b/source/mysql/unsafe/package.d
@@ -1,5 +1,5 @@
 /++
-Imports all of $(LINK2 https://github.com/mysql-d/mysql-native, mysql-native).
+Imports all of $(LINK2 https://github.com/mysql-d/mysql-native, mysql-native) (unsafe versions).
 
 This module will import all modules that use the unsafe API of the mysql
 library. Please import `mysql.safe` for the safe version.
diff --git a/source/mysql/unsafe/pool.d b/source/mysql/unsafe/pool.d
@@ -1,9 +1,9 @@
 /++
 Connect to a MySQL/MariaDB database using vibe.d's
-$(LINK2 http://vibed.org/api/vibe.core.connectionpool/ConnectionPool, ConnectionPool).
+$(LINK2 http://vibed.org/api/vibe.core.connectionpool/ConnectionPool, ConnectionPool) (unsafe version).
 
-This aliases `mysql.impl.pool.MySQLPoolImpl!false` as MySQLPool. Please see the
-`mysql.impl.pool` moddule for documentation on how to use MySQLPool.
+This aliases `mysql.impl.pool.MySQLPoolImpl!false` as `MySQLPool`. Please see the
+`mysql.impl.pool` moddule for documentation on how to use `MySQLPool`.
 
 This is the unsafe version of mysql's pool module, and as such uses only @system
 callback delegates. If you wish to use @safe callbacks, import
diff --git a/source/mysql/unsafe/prepared.d b/source/mysql/unsafe/prepared.d
@@ -1,6 +1,6 @@
 /++
-This module publicly imports `mysql.impl.prepared`. See that module for
-documentation on using prepared statements with a MySQL server.
+This module publicly imports `mysql.impl.prepared` (unsafe version). See that
+module for documentation on using prepared statements with a MySQL server.
 
 This module also aliases the unsafe versions of structs to the original struct
 names to aid in backwards compatibility.
diff --git a/source/mysql/unsafe/result.d b/source/mysql/unsafe/result.d
@@ -1,5 +1,5 @@
 /++
-This module publicly imports `mysql.impl.result`. See that module for documentation on how to use result and result range structures.
+This module publicly imports `mysql.impl.result`. See that module for documentation on how to use result and result range structures (unsafe versions).
 
 This module also aliases the unsafe versions of structs to the original struct
 names to aid in backwards compatibility.
