Docs: Spelling and other... [ci skip]

Author: Abscissa

ABOUT_PREPARED_V2.md

@@ -35,10 +35,10 @@ implementation *and* API of prepared statements is in `PreparedImpl`.
 ddox-generated documentation, AND no longer accomplishes anything *anyway*
 now that `PreparedImpl` no longer has any dtor (for various complicated
 reasons relating to struct dtors, the auto-purge feature from v1.1.4 and
-recognizing that manual release of statements from the server isn't stictly
+recognizing that manual release of statements from the server isn't strictly
 necessary, being per-connection after all).
 
-6. Mysql-native is not currently tempated on connection type, it uses a literal
+6. Mysql-native is not currently templated on connection type, it uses a literal
 `Connection` throughout. Unfortunately, this means the `LockedConnection!Connection`
 returned by Vibe.d's connection pools (which `MySQLPool` is based on) gets
 downgraded to a mere `Connection`. Ordinarily this would be fine if it was only
@@ -51,36 +51,36 @@ to correct this just to still compile anyway.
 Why these problems?
 -------------------
 
-I believe, for the most part, these issues are ultimately symptomatic of the
+I think, for the most part, these issues are ultimately symptomatic of the
 Prepared abstraction not accurately matching the reality. Thus, it needs
 high-level rethinking:
 
 Currently, `Prepared` (just like the original functionality in the old
 pre-v1.0.0 `Command` struct) is designed around the low-level reality that
 MySQL ties prepared statements to individual connections. But then, instead
 of treating prepared statements as something owned by a connection (as they
-realistically are), `Prepared` flips this around and *has a* connection,
-instead of the reality that a connection *has a* prepared statement.
+realistically are), `Prepared` flips this around and *has a* connection
+instead.
 
 It's also wrong on a higher level: Conceptually, to a database's human user,
 a prepared statement is...an SQL statement...that just has special "slots"
 for parameters and provides certain benefits. To a user, that's it, nothing
 more. That these particular statements happen to be tied to individual
 connections is merely an implementation detail of the communications protocol. 
 
-I believe these disconnects are the main cause of the above problems with `Prepared`.
+I believe these disconnects are the major cause of the above problems with `Prepared`.
 
 Solution for v2.0.0:
 --------------------
 
 Originally, I was thinking about (if anything *at all*) *maybe* offering an
 additional abstraction over top `Prepared` which manages prepared statements
 across multiple connections. But that would only address the first problem
-above, not all of them, and I now believe would liklely create additional
+above, not all of them, and I now believe would likely create additional
 mess and problems due to the original disconnect only being covered up,
-not resoloved.
+not resolved.
 
-So I think a re-design is warranted:
+So I think a redesign is warranted:
 
 - Get rid of `PreparedImpl`. Just have a `Prepared` struct and be done with it.
 In the unlikely case anyone really does need deterministic server-side release
@@ -103,7 +103,7 @@ automatically creates it.
 
 - `struct Prepared` itself shouldn't have any "release" or "register"
 functionality of its own, at all. That should be fully considered a
-charactaristic of the communications channel, not a charactaristic of
+charactaristic of the communications channel, not a characteristic of
 statements.
 
 - `Connection` should have a `.release(Prepared)` to manually release a
@@ -112,8 +112,8 @@ the statement hasn't been registered on the connection, or has already been
 released (as defined by the statement's SQL string).
 
 - Any functionality to manually release a Prepared from ALL connections
-should be in `MySQLPool`. I'm undecided whether this would be essential
-for v2.0.0 or could be deferred until v2.1.0 or so.
+should be in `MySQLPool`. This will not be in v2.0.0 though,
+it is delayed until v2.1.0 or so.
 
 - Connection and MySQLPool should also have `.register(Prepared)`
 (or is there a better name?) to manually create a prepared statement on a
@@ -123,9 +123,10 @@ will be still be automatically registered when its actually used.
 
 - When a statement is manually registered on a MySQLPool (as opposed to
 a Connection), The MySQLPool will manually register it on all
-currenty-open connections. After this point, the statement will automatically
+currently-open connections. After this point, the statement will automatically
 be registered on all new connections, immediately upon each new connection's
-creation, until `MySQLPool.release` is called on the statement.
+creation, until `MySQLPool.release` is called on the statement. This will also
+not be in v2.0.0 though, it is delayed until v2.1.0 or so.
 
 - In the future, other functionality could be added:
 `Connection/MySQLPool.releaseAllPrepared`, `Connection/MySQLPool.releaseStalePrepared`,
@@ -164,22 +165,22 @@ value in that.
 
 It could be argued that mysql-native is, in some ways, higher level than
 that original charter, and the same could be said for some of these changes.
-However, I don't beleive these changes make it too high-level for the vast
+However, I don't think these changes make it too high-level for the vast
 majority of use-cases, and I do believe these higher-level interfaces are
 more than worthwhile and moving in a very good direction for the average D
 database user.
 
 So what of the need for a stripped-down low-level API?
 ------------------------------------------------------
 
-First off all, there's nothing stopping other high-level DB libs from basing
+First of all, there's nothing stopping other high-level DB libs from basing
 their MySQL/MariaDB support on top of mysql-native's higher-level interfaces.
 That's entirely viable, and may even make things easier for the lib developers.
 And mysql-native *does* intend to reduce any overhead it does have and keep
 that to a minimum, even for high-level functionality (IMO, that's part of D's
 own charter, after all).
 
-But aside from that: For the sake of sensible code hygeine and maintainability,
+But aside from that: For the sake of sensible code hygiene and maintainability,
 my intention for the near-term future of this library is to clean up the
 internal design and separate all the low-level communications code out of the
 higher-level interfaces. This will have the additional benefit of opening the

MIGRATING_TO_V2.md

@@ -12,7 +12,7 @@ of the change in
 Unfortunately, these improvements have necessitated some breaking
 changes to the API for the
 [Prepared](http://semitwist.com/mysql-native/mysql/prepared/Prepared.html)
-struct. Any code which uses prepared statements will need a small update.
+struct. Any code which uses prepared statements will need some small updates.
 
 The changes needed in your code are simple syntactical changes. Before,
 in v1.x.x, you would call the exec/query functions on your Prepared
@@ -50,7 +50,7 @@ handles all the details necessary to make this work. If you wish to know
 exactly how this is done, see
 [ABOUT_PREPARED_V2.md](https://github.com/mysql-d/mysql-native/blob/master/ABOUT_PREPARED_V2.md).
 
-Also, note that `prepare()` function has moved from `mysql.prepared` to
+Also, note that the `prepare()` function has moved from `mysql.prepared` to
 `mysql.connection` as it is specific to `mysql.connection.Connection`, and
 this helps keep `mysql.prepared` completely non-dependent on `mysql.connection`.
 

README.md

@@ -5,7 +5,7 @@ client driver for MySQL and MariaDB.
 
 This package attempts to provide composite objects and methods that will
 allow a wide range of common database operations, but be relatively easy to
-use. It has no dependecies on GPL header files or libraries, instead communicating
+use. It has no dependencies on GPL header files or libraries, instead communicating
 directly with the server via the
 [published client/server protocol](http://dev.mysql.com/doc/internals/en/client-server-protocol.html).
 
@@ -40,7 +40,6 @@ The primary interfaces:
 - [exec()](http://semitwist.com/mysql-native/mysql/commands/exec.html): Plain old SQL statement that does NOT return rows (like INSERT/UPDATE/CREATE/etc), returns number of rows affected
 - [query()](http://semitwist.com/mysql-native/mysql/commands/query.html): Execute an SQL statement that DOES return rows (ie, SELECT) and handle the rows one at a time, as an input range.
 - [queryRow()](http://semitwist.com/mysql-native/mysql/commands/queryRow.html): Execute an SQL statement and get the first row.
-- [queryRowTuple()](http://semitwist.com/mysql-native/mysql/commands/queryRowTuple.html): Execute an SQL statement and get the first row into a matching tuple of D variables.
 - [queryValue()](http://semitwist.com/mysql-native/mysql/commands/queryValue.html): Execute an SQL statement and get the first value in the first row.
 - [prepare()](http://semitwist.com/mysql-native/mysql/prepared/prepare.html): Create a prepared statement
 - [Prepared](http://semitwist.com/mysql-native/mysql/prepared/PreparedImpl.html): A prepared statement, optionally pass it to the exec/query function in place of an SQL string.

source/mysql/commands.d

@@ -126,10 +126,10 @@ package bool execQueryImpl(Connection conn, ExecQueryImplInfo info)
 }
 
 /++
-Execute a one-off SQL command, such as INSERT/UPDATE/CREATE/etc.
+Execute an SQL command or prepared statement, such as INSERT/UPDATE/CREATE/etc.
 
 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
+(otherwise, use one of the `query` functions instead.) If the SQL command does
 produces a result set (such as SELECT), `mysql.exceptions.MYXResultRecieved`
 will be thrown.
 
@@ -163,13 +163,13 @@ ulong exec(Connection conn, ref Prepared prepared)
 /++
 This function is provided ONLY as a temporary aid in upgrading to mysql-native v2.0.0.
 
-See `BackwardCompatPrepared` for more info.
+See `mysql.connection.BackwardCompatPrepared` for more info.
 +/
-ulong exec(Connection conn, ref BackwardCompatPrepared prepared)
+ulong exec(Connection conn, ref BackwardCompatPrepared bcp)
 {
-	auto p = prepared.prepared;
+	auto p = bcp.prepared;
 	auto result = exec(conn, p);
-	prepared._prepared = p;
+	bcp._prepared = p;
 	return result;
 }
 
@@ -188,11 +188,11 @@ package ulong execImpl(Connection conn, ExecQueryImplInfo info)
 }
 
 /++
-Execute a one-off SQL SELECT command where you want to deal with the
-result set one row at a time.
+Execute an SQL SELECT command or prepared statement.
 
-If you need random access to the resulting `mysql.result.Row` elements,
-simply call $(LINK2 https://dlang.org/phobos/std_array.html#array, `std.array.array()`)
+This returns an input range of `mysql.result.Row`, so if you need random access
+to the `mysql.result.Row` elements, simply call
+$(LINK2 https://dlang.org/phobos/std_array.html#array, `std.array.array()`)
 on the result.
 
 If the SQL command does not produce a result set (such as INSERT/CREATE/etc),
@@ -240,13 +240,13 @@ ResultRange query(Connection conn, ref Prepared prepared, ColumnSpecialization[]
 /++
 This function is provided ONLY as a temporary aid in upgrading to mysql-native v2.0.0.
 
-See `BackwardCompatPrepared` for more info.
+See `mysql.connection.BackwardCompatPrepared` for more info.
 +/
-ResultRange query(Connection conn, ref BackwardCompatPrepared prepared, ColumnSpecialization[] csa = null)
+ResultRange query(Connection conn, ref BackwardCompatPrepared bcp, ColumnSpecialization[] csa = null)
 {
-	auto p = prepared.prepared;
+	auto p = bcp.prepared;
 	auto result = query(conn, p, csa);
-	prepared._prepared = p;
+	bcp._prepared = p;
 	return result;
 }
 
@@ -266,7 +266,8 @@ package ResultRange queryImpl(ColumnSpecialization[] csa,
 }
 
 /++
-Execute a one-off SQL SELECT command where you only want the first `mysql.result.Row` (if any).
+Execute an SQL SELECT command or prepared statement where you only want the
+first `mysql.result.Row`, if any.
 
 If the SQL command does not produce a result set (such as INSERT/CREATE/etc),
 then `mysql.exceptions.MYXNoResultRecieved` will be thrown. Use
@@ -308,13 +309,13 @@ Nullable!Row queryRow(Connection conn, ref Prepared prepared, ColumnSpecializati
 /++
 This function is provided ONLY as a temporary aid in upgrading to mysql-native v2.0.0.
 
-See `BackwardCompatPrepared` for more info.
+See `mysql.connection.BackwardCompatPrepared` for more info.
 +/
-Nullable!Row queryRow(Connection conn, ref BackwardCompatPrepared prepared, ColumnSpecialization[] csa = null)
+Nullable!Row queryRow(Connection conn, ref BackwardCompatPrepared bcp, ColumnSpecialization[] csa = null)
 {
-	auto p = prepared.prepared;
+	auto p = bcp.prepared;
 	auto result = queryRow(conn, p, csa);
-	prepared._prepared = p;
+	bcp._prepared = p;
 	return result;
 }
 
@@ -334,8 +335,8 @@ package Nullable!Row queryRowImpl(ColumnSpecialization[] csa, Connection conn,
 }
 
 /++
-Execute a one-off SQL SELECT command where you only want the first `mysql.result.Row`,
-and place result values into a set of D variables.
+Execute an SQL SELECT command or prepared statement where you only want the
+first `mysql.result.Row`, and place result values into a set of D variables.
 
 This method will throw if any column type is incompatible with the corresponding D variable.
 
@@ -375,13 +376,13 @@ void queryRowTuple(T...)(Connection conn, ref Prepared prepared, ref T args)
 /++
 This function is provided ONLY as a temporary aid in upgrading to mysql-native v2.0.0.
 
-See `BackwardCompatPrepared` for more info.
+See `mysql.connection.BackwardCompatPrepared` for more info.
 +/
-void queryRowTuple(T...)(Connection conn, ref BackwardCompatPrepared prepared, ref T args)
+void queryRowTuple(T...)(Connection conn, ref BackwardCompatPrepared bcp, ref T args)
 {
-	auto p = prepared.prepared;
+	auto p = bcp.prepared;
 	queryRowTuple(conn, p, args);
-	prepared._prepared = p;
+	bcp._prepared = p;
 }
 
 /// Common implementation for `queryRowTuple` overloads.
@@ -425,7 +426,7 @@ unittest
 }
 
 /++
-Execute a one-off SQL SELECT command and returns a single value,
+Execute an SQL SELECT command or prepared statement and return a single value:
 the first column of the first row received.
 
 If the query did not produce any rows, or the rows it produced have zero columns,
@@ -475,13 +476,13 @@ Nullable!Variant queryValue(Connection conn, ref Prepared prepared, ColumnSpecia
 /++
 This function is provided ONLY as a temporary aid in upgrading to mysql-native v2.0.0.
 
-See `BackwardCompatPrepared` for more info.
+See `mysql.connection.BackwardCompatPrepared` for more info.
 +/
-Nullable!Variant queryValue(Connection conn, ref BackwardCompatPrepared prepared, ColumnSpecialization[] csa = null)
+Nullable!Variant queryValue(Connection conn, ref BackwardCompatPrepared bcp, ColumnSpecialization[] csa = null)
 {
-	auto p = prepared.prepared;
+	auto p = bcp.prepared;
 	auto result = queryValue(conn, p, csa);
-	prepared._prepared = p;
+	bcp._prepared = p;
 	return result;
 }