Documentation edits/fixes/cleanup for Alcatel docs.

ndb/include/ndbapi/Ndb.hpp

@@ -51,20 +51,20 @@
 
    The procedure for using transactions is as follows:
    -# Start transaction (instantiate an NdbTransaction object)
-   -# Add and define operations associated with the transaction using the
-      NdbOperation, NdbScanOperation, NdbIndexOperation, and NdbIndexScanOperation classes.
-   -# Execute transaction
+   -# Add and define operations associated with the transaction using instances of one or more of the
+      NdbOperation, NdbScanOperation, NdbIndexOperation, and NdbIndexScanOperation classes
+   -# Execute transaction (call NdbTransaction::execute())
 
-   The execution can be of two different types, 
+   The operation can be of two different types, 
    <var>Commit</var> or <var>NoCommit</var>.
-   If the execution is of type <var>NoCommit</var>, 
-   then the application program executes part of a transaction,
+   If the operation is of type <var>NoCommit</var>, 
+   then the application program executes the operation part of a transaction,
    but without actually committing the transaction.
-   After executing a <var>NoCommit</var> transaction, the program can continue 
+   After executing a <var>NoCommit</var> operation, the program can continue 
    to add and define more operations to the transaction
    for later execution.
 
-   If the execute is of type <var>Commit</var>, then the transaction is
+   If the operation is of type <var>Commit</var>, then the transaction is
    immediately committed. The transaction <em>must</em> be closed after it has been 
    commited (event if commit fails), and no further addition or definition of 
    operations for this transaction is allowed.
@@ -78,15 +78,16 @@
        (typically created using Ndb::startTransaction()).
        At this point, the transaction is only being defined,
        and is not yet sent to the NDB kernel.
-    -# Define operations and add them to the transaction, using 
-       NdbTransaction::getNdbOperation(),
-       NdbTransaction::getNdbScanOperation(),
-       NdbTransaction::getNdbIndexOperation(), or
-       NdbTransaction::getNdbIndexScanOperation(),
-       and methods of the respective NdbOperation class.
+    -# Define operations and add them to the transaction, using one or more of
+       - NdbTransaction::getNdbOperation()
+       - NdbTransaction::getNdbScanOperation()
+       - NdbTransaction::getNdbIndexOperation()
+       - NdbTransaction::getNdbIndexScanOperation()
+       along with the appropriate methods of the respective NdbOperation class 
+       (or one possiblt one or more of its subclasses).
        Note that the transaction has still not yet been sent to the NDB kernel.
     -# Execute the transaction, using the NdbTransaction::execute() method.
-    -# Close the transaction (using Ndb::closeTransaction()).
+    -# Close the transaction (call Ndb::closeTransaction()).
   
    For an example of this process, see the program listing in 
    @ref ndbapi_simple.cpp.

ndb/include/ndbapi/ndb_cluster_connection.hpp

@@ -20,14 +20,14 @@
 
 /**
  * @class Ndb_cluster_connection
- * @brief Represents a connection to a cluster of storage nodes
+ * @brief Represents a connection to a cluster of storage nodes.
  *
- * Always start your application program by creating a
- * Ndb_cluster_connection object. Your application should contain
- * only one Ndb_cluster_connection.  Your application connects to
- * a cluster management server when method connect() is called.
- * With the method wait_until_ready() it is possible to wait
- * for the connection to one or several storage nodes.
+ * Any NDB application program should begin with the creation of a
+ * single Ndb_cluster_connection object, and should make use of one
+ * and only one Ndb_cluster_connection. The application connects to
+ * a cluster management server when this object's connect() method is called.
+ * By using the wait_until_ready() method it is possible to wait
+ * for the connection to reach one or more storage nodes.
  */
 class Ndb_cluster_connection {
 public:
@@ -43,16 +43,19 @@ public:
   /**
    * Connect to a cluster management server
    *
-   * @param no_retries specifies the number of retries to perform
-   *        if the connect fails, negative number results in infinite
-   *        number of retries
+   * @param no_retries specifies the number of retries to attempt
+   *        in the event of connection failure; a negative value 
+   *        will result in the attempt to connect being repeated 
+   *        indefinitely
+   *
    * @param retry_delay_in_seconds specifies how often retries should
    *        be performed
-   * @param verbose specifies if the method should print progess
    *
-   * @return 0 if success, 
-   *         1 if retriable error,
-   *        -1 if non-retriable error
+   * @param verbose specifies if the method should print a report of its progess
+   *
+   * @return 0 = success, 
+   *         1 = recoverable error,
+   *        -1 = non-recoverable error
    */
   int connect(int no_retries=0, int retry_delay_in_seconds=1, int verbose=0);
 
@@ -61,15 +64,15 @@ public:
 #endif
 
   /**
-   * Wait until one or several storage nodes are connected
+   * Wait until the requested connection with one or more storage nodes is successful
    *
    * @param time_out_for_first_alive number of seconds to wait until
-   *        first alive node is detected
+   *        first live node is detected
    * @param timeout_after_first_alive number of seconds to wait after
-   *        first alive node is detected
+   *        first live node is detected
    *
-   * @return 0 all nodes alive,
-   *         > 0 at least one node alive,
+   * @return = 0 all nodes live,
+   *         > 0 at least one node live,
    *         < 0 error
    */
   int wait_until_ready(int timeout_for_first_alive,