doc: small tweaks to Doxygen documentation (#1267)

Fixed missing documentation for SessionPoolOptions. Fixed documentation
for some of the `*Param` classes, they were picking up the documentation
for the group of classes, not their own docs. Made documentation for
`*Param` consistent. Fixed broken link in `RowStreamIterator` docs,
apparently Doxygen does not expand links in the brief document.

Author: coryan

google/cloud/spanner/connection.h

@@ -59,13 +59,14 @@ class Connection {
 
   //@{
   /**
-   * Defines the arguments for each member function.
+   * @name Defines the arguments for each member function.
    *
    * Applications may define classes derived from `Connection`, for example,
    * because they want to mock the class. To avoid breaking all such derived
    * classes when we change the number or type of the arguments to the member
    * functions we define light weight structures to pass the arguments.
    */
+
   /// Wrap the arguments to `Read()`.
   struct ReadParams {
     Transaction transaction;

google/cloud/spanner/database_admin_connection.h

@@ -62,7 +62,7 @@ class DatabaseAdminConnection {
 
   //@{
   /**
-   * Define the arguments for each member function.
+   * @name Define the arguments for each member function.
    *
    * Applications may define classes derived from `DatabaseAdminConnection`, for
    * example, because they want to mock the class. To avoid breaking all such

google/cloud/spanner/instance_admin_connection.h

@@ -73,7 +73,7 @@ class InstanceAdminConnection {
 
   //@{
   /**
-   * Define the arguments for each member function.
+   * @name Define the arguments for each member function.
    *
    * Applications may define classes derived from `InstanceAdminConnection`,
    * for example, because they want to mock the class. To avoid breaking all
@@ -114,7 +114,7 @@ class InstanceAdminConnection {
   };
 
   /**
-   * The parameters for a `ListInstances()` request.
+   * Wrap the arguments for `ListInstances()`.
    */
   struct ListInstancesParams {
     /**

google/cloud/spanner/row.h

@@ -228,12 +228,12 @@ Row MakeTestRow(Ts&&... ts) {
 }
 
 /**
- * A `RowStreamIterator` is an [Input Iterator][input-iterator] that returns a
+ * A `RowStreamIterator` is an _Input Iterator_ (see below) that returns a
  * sequence of `StatusOr<Row>` objects.
  *
- * As an Input Iterator, the sequence may only be consumed once. Default
- * constructing a `RowStreamIterator` creates an instance that represents
- * "end".
+ * As an [Input Iterator][input-iterator], the sequence may only be consumed
+ * once. Default constructing a `RowStreamIterator` creates an instance that
+ * represents "end".
  *
  * @note The term "stream" in this name refers to the general nature
  *     of the the data source, and is not intended to suggest any similarity to

google/cloud/spanner/session_pool_options.h

@@ -29,6 +29,22 @@ inline namespace SPANNER_CLIENT_NS {
 // What action to take if the session pool is exhausted.
 enum class ActionOnExhaustion { kBlock, kFail };
 
+/**
+ * Controls the session pool maintained by a `spanner::Client`.
+ *
+ * Creating Cloud Spanner sessions is an expensive operation. The
+ * [recommended practice][spanner-sessions-doc] is to maintain a cache (or pool)
+ * of sessions in the client side. This class controls the initial size of this
+ * pool, and how the pool grows (or shrinks) as needed.
+ *
+ * @note If no sessions are available to perform an operation the client library
+ *     blocks until new sessions are available (either released by other threads
+ *     or allocated on-demand, depending on the active constraints). It is
+ *     also possible to configure the client to fail a request when the session
+ *     pool is exhausted.
+ *
+ * [spanner-sessions-doc]: https://cloud.google.com/spanner/docs/sessions
+ */
 class SessionPoolOptions {
  public:
   /**