mgmapi.h, Ndb.hpp: Various fixes in Doxygen comments

ndb/include/mgmapi/mgmapi.h

@@ -38,7 +38,7 @@
  *  -# An integer value.
  *     A value of <b>-1</b> indicates an error.
  *  -# A pointer value.  A <var>NULL</var> value indicates an error;
- *     Otherwise, the return value must be <code>free()</code>ed by the user of the MGM API.
+ *     otherwise, the return value must be freed by the user of the MGM API.
  *
  * Error conditions can be identified by using the appropriate
  * error-reporting functions.

ndb/include/ndbapi/Ndb.hpp

@@ -23,76 +23,76 @@
    The <em>NDB API</em> is a MySQL Cluster application interface 
    that implements transactions.
    The NDB API consists of the following fundamental classes:
-   - Ndb_cluster_connection class representing a connection to a cluster, 
-   - Ndb is the main class representing the database, 
-   - NdbTransaction represents a transaction, 
-   - NdbOperation represents a operation using primary key,
-   - NdbScanOperation represents a operation performing a full table scan.
-   - NdbIndexOperation represents a operation using a unique hash index,
-   - NdbIndexScanOperation represents a operation performing a scan using
+   - <code>Ndb_cluster_connection</code>, representing a connection to a cluster, 
+   - <code>Ndb</code> is the main class, representing the database, 
+   - <code>NdbTransaction</code> represents a transaction, 
+   - <code>NdbOperation</code> represents an operation using a primary key,
+   - <code>NdbScanOperation</code> represents an operation performing a full table scan.
+   - <code>NdbIndexOperation</code> represents an operation using a unique hash index,
+   - <code>NdbIndexScanOperation</code> represents an operation performing a scan using
      an ordered index,
-   - NdbRecAttr represents the value of an attribute, and
-   - NdbDictionary represents meta information about tables and attributes.
-   - NdbError contains a specification of an error.
+   - <code>NdbRecAttr</code> represents an attribute value
+   - <code>NdbDictionary</code> represents meta information about tables and attributes.
+   - <code>NdbError</code> contains the specification for an error.
    There are also some auxiliary classes.
      
    The main structure of an application program is as follows:
-   -# Construct and connect to a cluster using the Ndb_cluster_connection
+   -# Construct and connect to a cluster using the <code>Ndb_cluster_connection</code>
       object.
-   -# Construct and initialize Ndb object(s).
-   -# Define and execute transactions using NdbTransaction and Ndb*Operation.
-   -# Delete Ndb objects
-   -# Delete connection to cluster
+   -# Construct and initialize <code>Ndb</code> object(s).
+   -# Define and execute transactions using <code>NdbTransaction</code> and <code>Ndb*Operation</code>.
+   -# Delete <code>Ndb</code> objects
+   -# Delete cluster connection
 
    The main structure of a transaction is as follows:
-   -# Start transaction, a NdbTransaction
-   -# Add and define operations (associated with the transaction),
-      Ndb*Operation
+   -# Start transaction (an <code>NdbTransaction</code>)
+   -# Add and define operations associated with the transaction using
+      <code>Ndb*Operation</code>
    -# Execute transaction
 
-   The execute can be of two different types, 
-   <em>Commit</em> or <em>NoCommit</em>.
+   The execution can be of two different types, 
+   <var>Commit</var> or <var>NoCommit</var>.
 */
 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 /**
-   (The execute can also be divided into three 
-   steps: prepare, send, and poll to get asynchronous
+   (A transaction's execution can also be divided into three 
+   steps: prepare, send, and poll. This allows us to perform asynchronous
    transactions.  More about this later.)
 */
 #endif
 /** 
-   If the execute is of type NoCommit, 
+   If the execution is of type <var>NoCommit</var>, 
    then the application program executes part of a transaction,
    but without committing the transaction.
-   After a NoCommit type of execute, the program can continue 
+   After executing a <var>NoCommit</var> transaction, the program can continue 
    to add and define more operations to the transaction
    for later execution.
 
-   If the execute is of type Commit, then the transaction is
-   committed and no further adding and defining of operations 
+   If the execute is of type <var>Commit</var>, then the transaction is
+   committed, and no further addition or definition of operations 
    is allowed.
 
 
    @section secSync                     Synchronous Transactions
   
-   Synchronous transactions are defined and executed in the following way.
+   Synchronous transactions are defined and executed as follows:
   
-    -# Start (create) transaction (the transaction will be 
-       referred to by an NdbTransaction object, 
-       typically created by Ndb::startTransaction).
-       At this step the transaction is being defined.
-       It is not yet sent to the NDB kernel.
-    -# Add and define operations to the transaction 
-       (using NdbTransaction::getNdb*Operation and
-       methods from class Ndb*Operation).
-       The transaction is still not sent to the NDB kernel.
-    -# Execute the transaction (using NdbTransaction::execute).
-    -# Close the transaction (using Ndb::closeTransaction).
+    -# Start (create) the transaction, which is
+       referenced by an <code>NdbTransaction</code> object 
+       (typically created using <code>Ndb::startTransaction()</code>).
+       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 <code>NdbTransaction::getNdb*Operation()</code> and
+       methods of the <code>Ndb*Operation</code> class.
+       Note that the transaction has still not yet been sent to the NDB kernel.
+    -# Execute the transaction, using the <code>NdbTransaction::execute()</code> method.
+    -# Close the transaction (using <code>Ndb::closeTransaction()</code>).
   
-   See example program in section @ref ndbapi_example1.cpp.
+   For an example of this process, see the program listing in @ref ndbapi_example1.cpp.
 
    To execute several parallel synchronous transactions, one can either 
-   use multiple Ndb objects in several threads or start multiple 
+   use multiple <code>Ndb</code> objects in several threads, or start multiple 
    applications programs.  
 */
 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
@@ -104,8 +104,9 @@
 /**  
    @section secNdbOperations            Operations
 
-   Each transaction (NdbTransaction object) consist of a list of 
-   operations (Ndb*Operation objects).
+   Each <code>NdbTransaction</code> (that is, a transaction) 
+   consists of a list of operations which are represented by instances 
+   of <code>Ndb*Operation</code>.
 */
 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 /**
@@ -116,17 +117,17 @@
 #endif
 /**
    <h3>Single row operations</h3>
-   After the operation is created using NdbTransaction::getNdbOperation
-   (or NdbTransaction::getNdbIndexOperation),
-   it is defined in the following three steps:
-   -# Defining standard operation type
-      (e.g. using NdbOperation::readTuple)
-   -# Specifying search conditions 
-      (e.g. using NdbOperation::equal)
-   -# Specify attribute actions 
-      (e.g. using NdbOperation::getValue)
-
-   Example code (using an NdbOperation and excluding error handling):
+   After the operation is created using <code>NdbTransaction::getNdbOperation()</code>
+   (or <code>NdbTransaction::getNdbIndexOperation()</code>), it is defined in the following 
+   three steps:
+   -# Define the standard operation type, using <code>NdbOperation::readTuple()</code>
+   -# Specify search conditions, using <code>NdbOperation::equal()</code>
+   -# Specify attribute actions, using <code>NdbOperation::getValue()</code>
+
+   Here are two brief examples illustrating this process. For the sake of brevity, 
+   we omit error-handling.
+   
+   This first example uses an <code>NdbOperation</code>:
    @code
      // 1. Create
      MyOperation= MyTransaction->getNdbOperation("MYTABLENAME");
@@ -140,10 +141,10 @@
      // 4. Attribute Actions
      MyRecAttr= MyOperation->getValue("ATTR2", NULL);
    @endcode
-   For more examples, see @ref ndbapi_example1.cpp and 
+   For additional examples of this sort, see @ref ndbapi_example1.cpp and 
    @ref ndbapi_example2.cpp.
 
-   Example code (using an NdbIndexOperation and excluding error handling):
+   The second example uses an <code>NdbIndexOperation</code>:
    @code
      // 1. Create
      MyOperation= MyTransaction->getNdbIndexOperation("MYINDEX", "MYTABLENAME");
@@ -157,9 +158,16 @@
      // 4. Attribute Actions 
      MyRecAttr = MyOperation->getValue("ATTR2", NULL);
    @endcode
-   For more examples, see @ref ndbapi_example4.cpp.
+   Another example of this second type can be found in @ref ndbapi_example4.cpp.
+
+   We will now discuss in somewhat greater detail each step involved in the creation 
+   and use of synchronous transactions.
 
+*/
+
+  //  Edit stop point - JS, 20041228 0425+1000
 
+/**
    <h4>Step 1: Define single row operation type</h4>
    The following types of operations exist:
     -# NdbOperation::insertTuple :