8.0.7 documentation update - post review fixes.

Author: rsomla1

doc/building.txt

@@ -29,7 +29,7 @@ Only out-of-source builds are supported. To configure a build, execute
 $ cmake <Connector/C++ source location>
 ~~~~~~~
 
-If Boost libraries are required and `cmake` can not find them, specify the
+If Boost libraries are required and `cmake` cannot find them, specify the
 correct location using the option:
 
 - `-DWITH_BOOST=<Boost location>`
@@ -38,8 +38,10 @@ By default a shared library is built. To build a static library, use the option:
 
 - `-DBUILD_STATIC=yes`
 
-The build system generated by `cmake` has install target which, by default, installs to `/usr/local/mysql/connector-c++-8.0`
-(`<User home>/MySQL/"MySQL Connector C++ 8.0"` on Windows). To change this default install location use the option:
+The build system generated by `cmake` has install target which, by default,
+installs to `/usr/local/mysql/connector-c++-8.0`
+(`<User home>/MySQL/"MySQL Connector C++ 8.0"` on Windows).
+To change this default install location use the option:
 
 - `-DCMAKE_INSTALL_PREFIX=<Install location>`
 
@@ -90,7 +92,9 @@ the Connector/C++ shared library:
 - `CCC/mysqlcppconn8-1-vsXX.dll` on Windows, where `-vs12` or `-vs14` prefix
   depends on the MSVC version used to build the connector
 
-The number 1 in the library name is the major ABI version of the library. It is part of the library name so that different versions of the library can be used at the same time on a single system.
+The number 1 in the library name is the major ABI version of the library. It
+is part of the library name so that different versions of the library can
+be used at the same time on a single system.
 
 On Unix and OS X also appropriate symbolic links are created. On Windows the
 import library for the DLL is created at `CCC/mysqlcppconn8.lib` (the `CCC/`
@@ -134,7 +138,8 @@ $ cmake --build . --config CCC
 ~~~~~~~
 
 This should create the `devapi_test` and `xapi_test` executables
-in the `run/` subdirectory of the build location. If testing static connector, pass `-DBUILD_STATIC=ON` option when configuring test applications.
+in the `run/` subdirectory of the build location. If testing static connector,
+pass the `-DBUILD_STATIC=ON` option when configuring test applications.
 
 @note
   On Windows, if the connector was built with the static runtime by specifying
@@ -160,8 +165,9 @@ started like this, the plugin will listen on port 13009 instead of
 the standard 33060 one.
 
 Now you can run one of the test programs and see the output similar to the
-one presented below. Test programs accept a connection string as an argument.
-If the server was started as described above, run the test program with the following connection string as a parameter:
+one presented below. Test programs accept a connection-string argument.
+If the server was started as described above, run the test program with
+the following connection string as a parameter:
 
 ~~~~~~~
 $ run/devapi_test mysqlx://[email protected]:13009
@@ -218,24 +224,27 @@ and XAPI), Connector/C++ also supports the legacy API based on JDBC4. This
 legacy API is implemented as a separate library with base name `mysqlcppconn`
 as opposed to `mysqlcppconn8` library implementing the new APIs.
 
-To build the legacy library pass `-DWITH_JDBC=ON` option during cmake
-configuration step (this option is disabled by default). This brings additional
-build dependencies that must be satisfied:
+To build the legacy library specify the `-DWITH_JDBC=ON` option during the cmake
+configuration step. This option is disabled by default. If specified, additional
+build dependencies must be satisfied:
 
-- The MySQL 8.0 client library is needed. If `cmake` can not find it at default
-  locations, pass `-DMYSQL_DIR=<path_to_mysql_server_dir>` option.
+- The MySQL 8.0 client library is needed. If `cmake` cannot find it at
+  the default locations, pass the `-DMYSQL_DIR=<path_to_mysql_server_dir>`
+  option.
 
 - Boost libraries are always required in this case. As explained above, use
-  `WITH_BOOST` option if `cmake` can not find Boost at default locations.
+  the `WITH_BOOST` option if `cmake` cannot find Boost at the default locations.
 
 @note
-  The code implementing legacy connector is inside `jdbc/` subdirectory of the
-  source tree. If sources are obtained from a git repository this sub-directory
-  must be fetched separately as a git sub-module. Invoke
-  `git submodule update --init` to populate contents of `jdbc/` subdirectory.
+  The code implementing the legacy connector is inside the `jdbc/` subdirectory
+  of the source tree. If sources are obtained from a git repository, this
+  subdirectory must be fetched separately as a git sub-module. Invoke
+  `git submodule update --init` to populate the contents of the `jdbc/`
+  subdirectory.
+
 
 If everything goes well, after building the connector the build location
-should contain additional legacy connector library:
+should contain an additional legacy connector library:
 
 - `libmysqlcppconn.so.7` on Unix
 - `libmysqlcppconn.7.dylib` on OS X
@@ -248,14 +257,14 @@ If building static libraries, the static legacy library has name:
   on Windows
 
 
-It is possible to build additional test application `jdbc_test` for testing
-the legacy connector library. To do this, pass `-DWITH_JDBC=ON` cmake option
+It is possible to build an additional test application `jdbc_test` for testing
+the legacy connector library. To do this, pass the `-DWITH_JDBC=ON` cmake option
 when configuring the build of test applications. Also, `MYSQL_DIR`
-and `WITH_BOOST` must be set of cmake can not find required dependencies.
+and `WITH_BOOST` must be set if cmake cannot find the required dependencies.
 
-The connection string accepted as argument of `jdbc_test` application must be
-in the form expected by JDBC API. The user name is passed as the 2nd argument.
-For example:
+The connection-string argument that the `jdbc_test` application accepts must
+be in the form specified by the JDBC API. The user name is passed as the second
+argument. For example:
 
 ~~~~~~~
 $ run/jdbc_test tcp://127.0.0.1:13009 root
@@ -264,17 +273,17 @@ $ run/jdbc_test tcp://127.0.0.1:13009 root
 
 Windows Notes                                                 @anchor win_notes
 -------------
-Connector/C++ uses C++11 language and for that reason it is not possible
+Connector/C++ uses the C++11 language and for that reason it is not possible
 to build it with Microsoft Visual Studio 2010 or earlier.
 
 On Windows one can request that Connector/C++ uses the static runtime library
-(The `/MT*` compiler option) by setting the cmake option `-DSTATIC_MSVCRT=yes`.
+(the `/MT*` compiler option) by setting the cmake option `-DSTATIC_MSVCRT=yes`.
 This might be necessary if code which uses Connector/C++ also uses the static
-runtime.  If building static library in this mode, the `-mt` suffix will
+runtime.  If building the static library in this mode, the `-mt` suffix will
 be added to its name to distinguish it from a library built in `/MD` mode.
 
 Selecting a cmake generator such as `"Visual Studio 14 2015 Win64"` vs
-`"Visual Studio 14 2015"` selects the 64 or 32 bit platform for which
+`"Visual Studio 14 2015"` selects the 64-bit or 32-bit platform for which
 the connector is built. An application which uses Connector/C++ must
 be built for the same platform as the connector.
 

doc/index.txt

@@ -3,11 +3,11 @@ MySQL Connector/C++ Documentation  {#mainpage}
 
 MySQL Connector/C++ is a library for applications written in C or C++ that
 communicate with MySQL database servers. Version 8.0 of Connector/C++
-implements three different APIs which can be used by applications...
+implements three different APIs which can be used by applications:
 
 - The new [X DevAPI] (@ref devapi) for applications written in C++.
 - The new [XAPI] (@ref xapi) for applications written in plain C.
-- The [legacy JDBC4 based API] (@ref jdbc_ref)
+- The [legacy JDBC4-based API] (@ref jdbc_ref)
   also implemented in version 1.1 of the connector.
 
 The new APIs give access to MySQL implementing a [document store]

doc/jdbc_ref.txt

@@ -1,42 +1,16 @@
-Connector/C++ 8.0 legacy C++ API based on JDBC4 Reference {#jdbc_ref}
+Connector/C++ 8.0 legacy C++ API based on JDBC4 {#jdbc_ref}
 =======================================
 
-Connector/C++ 8.0 supports the legacy C++ API based on JDBC4 specification.
+Connector/C++ 8.0 supports the legacy C++ API based on the JDBC4 specification.
 
 This allows an easy migration to Connector/C++ version 8.0 for applications
-that use Connector/C++ version 1.1. 
+that use Connector/C++ version 1.1.
 
 More detailed information about the legacy C++ API can be found in the
 [X MySQL Connector/C++ Developer Guide]
 (https://dev.mysql.com/doc/connector-cpp/en/)
 of MySQL online manual.
 
-Source distributions of Connector/C++ include an examples directory
-containing usage examples that explain how to use the following classes: 
-
- - `Connection`
-
- - `Driver`
-
- - `PreparedStatement`
-
- - `ResultSet`
-
- - `ResultSetMetaData`
-
- - `Statement`
-
- The examples cover:
-
- - Using the Driver class to connect to MySQL
-
- - Creating tables, inserting rows, fetching rows using (simple) statements
-
- - Creating tables, inserting rows, fetching rows using prepared statements
-
- - Hints for working around prepared statement limitations
-
- - Accessing result set metadata 
 
 ### Sample code which uses Connector/C++ with legacy C++ API ###
 
@@ -46,14 +20,14 @@ legacy C++ API.
 @note
   The connection is established over the legacy protocol and therefore
   X Plugin is not needed and the server does not need to support X Protocol.
-  
+
 After the connection is established the code executes a simple SQL statement
 and reads the result from the server. The source file can be found in
 testapp/jdbc_test.cc in the source distribution of Connector/C++ 8.0.
 See @ref usage for instructions on how to build the sample code.
 
-Each program which is using the legacy C++ API has to do the following
-includes:
+Each program which uses the legacy C++ API has to include the following
+headers:
 
 @dontinclude jdbc_test.cc
 @skip #include <jdbc/mysql_connection.h>
@@ -64,8 +38,8 @@ These headers are needed for using the `ResultSet` and `Statement` classes:
 @skip #include <jdbc/cppconn/resultset.h>
 @until #include <jdbc/cppconn/statement.h>
 
-Define the credentials for connecting, process command line params and
-other housekeeping stuff:
+Define the credentials for connecting, process command line parameters and
+other housekeeping:
 
 @skip #define DEFAULT_URI "tcp://127.0.0.1"
 @until try {
@@ -82,16 +56,16 @@ Make sure that you free con, the `sql::Connection` object, as soon as you do
 not need it any more. But do not explicitly free driver, the connector object.
 Connector/C++ takes care of freeing that.
 
-@note `get_mysql_driver_instance()` calls `get_driver_instance()`, which is 
+@note `get_mysql_driver_instance()` calls `get_driver_instance()`, which is
 not thread-safe. Either avoid invoking these methods from within multiple
 threads at once, or surround the calls with a mutex to prevent simultaneous
-execution in multiple threads. 
+execution in multiple threads.
 
  These methods can be used to check the connection state or reconnect:
 
  - `sql::Connection::isValid()` checks whether the connection is alive
 
- - `sql::Connection::reconnect()` reconnects if the connection has gone down 
+ - `sql::Connection::reconnect()` reconnects if the connection has gone down
 
 The `sql::Connection` is used to set the schema and create a statement:
 
@@ -115,14 +89,14 @@ prepared statements. If your query returns one result set, use
 `sql::Statement::executeQuery()` or `sql::PreparedStatement::executeQuery()`
 to run your query. Both methods return `sql::ResultSet` objects.
 By default, Connector/C++ buffers all result sets on the client to support
-cursors. 
+cursors.
 
 The code below walks through the entire result set row by row using
-`sql::ResultSet::next()` method, which returns `true` if the row was sucessfully
-read. Otherwise it returns `false`, which means we reached the end of the
-result set and there are no more rows to read.
+`sql::ResultSet::next()` method, which returns `true` if the row was
+successfully read. Otherwise it returns `false`, which means we reached the end
+of the result set and there are no more rows to read.
 
-The actual data is obtained trhough the getXxxx() functions such as
+The actual data is obtained through the getXxxx() functions such as
 `getInt(), getString()`, etc. The columns can be indexed by numbers in the
 order they are given inside the result set starting from 1.
 Alternatively the column name can be used as a string index.