Documentation edits/fixes/cleanup for Alcatel docs.

ndb/include/mgmapi/mgmapi.h

@@ -18,44 +18,44 @@
 #define MGMAPI_H
 
 /**
- * @mainpage NDB Cluster Management API
+ * @mainpage MySQL Cluster Management API
  *
- * The NDB Cluster Management API (MGM API) is a C API
- * that is used to:
- * - Start and stop database nodes (ndbd processes)
- * - Start and stop NDB Cluster backups
- * - Control the NDB Cluster log
- * - Perform other administrative tasks
+ * The MySQL Cluster Management API (MGM API) is a C language API
+ * that is used for:
+ * - Starting and stopping database nodes (ndbd processes)
+ * - Starting and stopping Cluster backups
+ * - Controlling the NDB Cluster log
+ * - Performing other administrative tasks
  *
  * @section  General Concepts
  *
  * Each MGM API function needs a management server handle
  * of type @ref NdbMgmHandle.
- * This handle is initally created by calling the
+ * This handle is created by calling the function 
  * function ndb_mgm_create_handle() and freed by calling 
  * ndb_mgm_destroy_handle().
  *
- * A function can return:
- *  -# An integer value.
- *     A value of <b>-1</b> indicates an error.
- *  -# A non-const pointer value.  A <var>NULL</var> value indicates an error;
+ * A function can return any of the following:
+ *  -# An integer value, with
+ *     a value of <b>-1</b> indicating an error.
+ *  -# A non-constant pointer value.  A <var>NULL</var> value indicates an error;
  *     otherwise, the return value must be freed
- *     by the user of the MGM API
- *  -# A const pointer value.  A <var>NULL</var> value indicates an error.
- *     Returned value should not be freed.
+ *     by the programmer
+ *  -# A constant pointer value, with a <var>NULL</var> value indicating an error.
+ *     The returned value should <em>not</em> be freed.
  *
  * Error conditions can be identified by using the appropriate
  * error-reporting functions ndb_mgm_get_latest_error() and 
  * @ref ndb_mgm_error.
  *
- * Below is an example of usage (without error handling for brevity).
+ * Here is an example using the MGM API (without error handling for brevity's sake).
  * @code
  *   NdbMgmHandle handle= ndb_mgm_create_handle();
  *   ndb_mgm_connect(handle,0,0,0);
  *   struct ndb_mgm_cluster_state *state= ndb_mgm_get_status(handle);
  *   for(int i=0; i < state->no_of_nodes; i++) 
  *   {
- *     printf("node with id=%d ", state->node_states[i].node_id);
+ *     printf("node with ID=%d ", state->node_states[i].node_id);
  *     if(state->node_states[i].version != 0)
  *       printf("connected\n");
  *     else
@@ -234,10 +234,10 @@ extern "C" {
    *   returned by ndb_mgm_get_status()
    *
    *   @note @ref node_status, @ref start_phase, @ref dynamic_id 
-   *         and @ref node_group are only relevant for database nodes
+   *         and @ref node_group are relevant only for database nodes
    */
   struct ndb_mgm_node_state {
-    /** NDB Cluster node id*/
+    /** NDB Cluster node ID*/
     int node_id;
     /** Type of NDB Cluster node*/
     enum ndb_mgm_node_type   node_type;
@@ -245,12 +245,12 @@ extern "C" {
     enum ndb_mgm_node_status node_status;
     /** Start phase.
      *
-     *  @note Start phase is only valid if node_type is
-     *        NDB_MGM_NODE_TYPE_NDB and node_status is 
+     *  @note Start phase is only valid if the <var>node_type</var> is
+     *        NDB_MGM_NODE_TYPE_NDB and the <var>node_status</var> is 
      *        NDB_MGM_NODE_STATUS_STARTING
      */
     int start_phase;
-    /** Id for heartbeats and master take-over (only valid for DB nodes)
+    /** ID for heartbeats and master take-over (only valid for DB nodes)
      */
     int dynamic_id;
     /** Node group of node (only valid for DB nodes)*/
@@ -261,9 +261,9 @@ extern "C" {
      *  management server
      */
     int connect_count;
-    /** Ip adress of node when it connected to the management server.
-     *  @note it will be empty if the management server has restarted
-     *        after the node connected.
+    /** IP address of node when it connected to the management server.
+     *  @note This value will be empty if the management server has restarted
+     *        since the node last connected.
      */
     char connect_address[
 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
@@ -273,11 +273,11 @@ extern "C" {
   };
 
   /**
-   *   State of all nodes in the cluster returned from 
+   *   State of all nodes in the cluster; returned from 
    *   ndb_mgm_get_status()
    */
   struct ndb_mgm_cluster_state {
-    /** No of entries in the node_states array */
+    /** Number of entries in the node_states array */
     int no_of_nodes;
     /** An array with node_states*/
     struct ndb_mgm_node_state node_states[
@@ -288,7 +288,7 @@ extern "C" {
   };
 
   /**
-   *   Default reply from the server (for future use, not used today)
+   *   Default reply from the server (reserved for future use)
    */
   struct ndb_mgm_reply {
     /** 0 if successful, otherwise error code. */
@@ -325,21 +325,21 @@ extern "C" {
 #endif
 
   /**
-   *   Log severities (used to filter the cluster log)
+   *   Log severity of errors. (Used to filter the cluster log.)
    */
   enum ndb_mgm_clusterlog_level {
     NDB_MGM_ILLEGAL_CLUSTERLOG_LEVEL = -1,
-    /* must range from 0 and up, indexes into an array */
+    /*  Must be a nonnegative integer (used for array indexing) */
     /** Cluster log on*/
     NDB_MGM_CLUSTERLOG_ON    = 0,
     /** Used in NDB Cluster developement */
     NDB_MGM_CLUSTERLOG_DEBUG = 1,
     /** Informational messages*/
     NDB_MGM_CLUSTERLOG_INFO = 2,
-    /** Conditions that are not error condition, but might require handling
+    /** Conditions that are not error condition, but might require special handling.
      */
     NDB_MGM_CLUSTERLOG_WARNING = 3,
-    /** Conditions that should be corrected */
+    /** Conditions that, while not fatal, should be corrected. */
     NDB_MGM_CLUSTERLOG_ERROR = 4,
     /** Critical conditions, like device errors or out of resources */
     NDB_MGM_CLUSTERLOG_CRITICAL = 5,
@@ -353,7 +353,7 @@ extern "C" {
   };
 
   /**
-   *  Log categories, used to set filter on the clusterlog using
+   *  Log categories, used in setting filters on the clusterlog using
    *  ndb_mgm_set_loglevel_clusterlog()
    */
   enum ndb_mgm_event_category {
@@ -362,11 +362,11 @@ extern "C" {
      */
     NDB_MGM_ILLEGAL_EVENT_CATEGORY = -1,
     /**
-     * Events during all kinds of startups
+     * Startup events
      */
     NDB_MGM_EVENT_CATEGORY_STARTUP = CFG_LOGLEVEL_STARTUP,
     /**
-     * Events during shutdown
+     * Shutdown events
      */
     NDB_MGM_EVENT_CATEGORY_SHUTDOWN = CFG_LOGLEVEL_SHUTDOWN,
     /**
@@ -374,15 +374,15 @@ extern "C" {
      */
     NDB_MGM_EVENT_CATEGORY_STATISTIC = CFG_LOGLEVEL_STATISTICS,
     /**
-     * Events regarding checkpoints
+     * Checkpoint events
      */
     NDB_MGM_EVENT_CATEGORY_CHECKPOINT = CFG_LOGLEVEL_CHECKPOINT,
     /**
-     * Events during node restart
+     * Node restart events
      */
     NDB_MGM_EVENT_CATEGORY_NODE_RESTART = CFG_LOGLEVEL_NODERESTART,
     /**
-     * Events on connection between cluster nodes
+     * Cluster node connection events
      */
     NDB_MGM_EVENT_CATEGORY_CONNECTION = CFG_LOGLEVEL_CONNECTION,
     /**
@@ -424,7 +424,8 @@ extern "C" {
    */
 
   /**
-   * Get latest error associated with a management server handle
+   *  Get the most recent error associated with the management server whose handle 
+   *  is used as the value of <var>handle</var>.
    *
    * @param   handle        Management handle
    * @return                Latest error code
@@ -432,7 +433,7 @@ extern "C" {
   int ndb_mgm_get_latest_error(const NdbMgmHandle handle);
 
   /**
-   * Get latest main error message associated with a handle
+   * Get the most recent general error message associated with a handle
    *
    * @param   handle        Management handle.
    * @return                Latest error message
@@ -440,9 +441,9 @@ extern "C" {
   const char * ndb_mgm_get_latest_error_msg(const NdbMgmHandle handle);
 
   /**
-   * Get latest error description associated with a handle
+   * Get the most recent error description associated with a handle
    *
-   * The error description gives some additional information to
+   * The error description gives some additional information regarding
    * the error message.
    *
    * @param   handle        Management handle.
@@ -452,7 +453,7 @@ extern "C" {
 
 #ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
   /**
-   * Get latest internal source code error line associated with a handle
+   * Get the most recent internal source code error line associated with a handle
    *
    * @param   handle        Management handle.
    * @return                Latest internal source code line of latest error
@@ -468,15 +469,15 @@ extern "C" {
    */
 
   /**
-   * Create a handle to a management server
+   * Create a handle to a management server.
    *
    * @return                 A management handle<br>
-   *                         or NULL if no management handle could be created.
+   *                         or <var>NULL</var> if no management handle could be created.
    */
   NdbMgmHandle ndb_mgm_create_handle();
 
   /**
-   * Destroy a management server handle
+   * Destroy a management server handle.
    *
    * @param   handle        Management handle
    */
@@ -489,7 +490,7 @@ extern "C" {
    */
 
   /**
-   * Set connect string to management server
+   * Sets the connectstring for a management server
    *
    * @param   handle         Management handle
    * @param   connect_string Connect string to the management server,
@@ -500,19 +501,19 @@ extern "C" {
    * <connectstring> := [<nodeid-specification>,]<host-specification>[,<host-specification>]
    * <nodeid-specification> := nodeid=<id>
    * <host-specification> := <host>[:<port>]
-   * <id> is an integer larger than 1 identifying a node in config.ini
+   * <id> is an integer greater than 1 identifying a node in config.ini
    * <port> is an integer referring to a regular unix port
-   * <host> is a string which is a valid Internet host address
+   * <host> is a string containing a valid network host address
    * @endcode
    */
   int ndb_mgm_set_connectstring(NdbMgmHandle handle,
 				const char *connect_string);
 
   /**
-   * Get connectstring used for connection
+   * Gets the connectstring used for a connection
    *
-   * @note returns what the connectstring defaults to if the 
-   *       ndb_mgm_set_connectstring() call has not been performed
+   * @note This function returns the default connectstring if no call to 
+   *       ndb_mgm_set_connectstring() has been performed
    *
    * @param   handle         Management handle
    *
@@ -521,7 +522,7 @@ extern "C" {
   const char *ndb_mgm_get_connectstring(NdbMgmHandle handle, char *buf, int buf_sz);
 
   /**
-   * Connect to a management server. Coonect string is set by
+   * Connects to a management server. Connectstring is set by
    * ndb_mgm_set_connectstring().
    *
    * @param   handle        Management handle.
@@ -531,7 +532,7 @@ extern "C" {
 		      int retry_delay_in_seconds, int verbose);
 
   /**
-   * Disconnect from a management server
+   * Disconnects from a management server
    *
    * @param  handle         Management handle.
    * @return                -1 on error.
@@ -539,17 +540,17 @@ extern "C" {
   int ndb_mgm_disconnect(NdbMgmHandle handle);
 
   /**
-   * Get nodeid used in the connection
+   * Gets connection node ID
    *
    * @param   handle         Management handle
    *
-   * @return                 node id, 0 indicated that no nodeid has been
+   * @return                 Node ID; 0 indicates that no node ID has been
    *                         specified
    */
   int ndb_mgm_get_configuration_nodeid(NdbMgmHandle handle);
 
   /**
-   * Get port used in the connection
+   * Gets connection port
    *
    * @param   handle         Management handle
    *
@@ -558,7 +559,7 @@ extern "C" {
   int ndb_mgm_get_connected_port(NdbMgmHandle handle);
 
   /**
-   * Get host used in the connection
+   * Gets connection host
    *
    * @param   handle         Management handle
    *
@@ -569,12 +570,12 @@ extern "C" {
 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
   /** @} *********************************************************************/
   /**
-   * @name Functions: Convert between different data formats
+   * @name Functions: Used to convert between different data formats
    * @{
    */
 
   /**
-   * Convert a string to a ndb_mgm_node_type
+   * Converts a string to an <var>ndb_mgm_node_type</var> value
    *
    * @param   type          Node type as string.
    * @return                NDB_MGM_NODE_TYPE_UNKNOWN if invalid string.
@@ -582,24 +583,24 @@ extern "C" {
   enum ndb_mgm_node_type ndb_mgm_match_node_type(const char * type);
 
   /**
-   * Convert an ndb_mgm_node_type to a string
+   * Converts an ndb_mgm_node_type to a string
    *
    * @param   type          Node type.
-   * @return                NULL if invalid id.
+   * @return                <var>NULL</var> if invalid ID.
    */
   const char * ndb_mgm_get_node_type_string(enum ndb_mgm_node_type type);
 
   /**
-   * Convert an ndb_mgm_node_type to a alias string
+   * Converts an ndb_mgm_node_type to a alias string
    *
    * @param   type          Node type.
-   * @return                NULL if invalid id.
+   * @return                <var>NULL</var> if the ID is invalid.
    */
   const char * ndb_mgm_get_node_type_alias_string(enum ndb_mgm_node_type type,
 						  const char **str);
 
   /**
-   * Convert a string to a ndb_mgm_node_status
+   * Converts a string to a <var>ndb_mgm_node_status</var> value
    *
    * @param   status        NDB node status string.
    * @return                NDB_MGM_NODE_STATUS_UNKNOWN if invalid string.
@@ -607,10 +608,10 @@ extern "C" {
   enum ndb_mgm_node_status ndb_mgm_match_node_status(const char * status);
 
   /**
-   * Convert an id to a string
+   * Converts an ID to a string
    *
    * @param   status        NDB node status.
-   * @return                NULL if invalid id.
+   * @return                <var>NULL</var> if invalid ID.
    */
   const char * ndb_mgm_get_node_status_string(enum ndb_mgm_node_status status);
 
@@ -621,18 +622,18 @@ extern "C" {
 
   /** @} *********************************************************************/
   /**
-   * @name Functions: State of cluster
+   * @name Functions: Cluster status
    * @{
    */
 
   /**
-   * Get status of the nodes in an NDB Cluster
+   * Gets status of the nodes in an NDB Cluster
    *
-   * Note the caller must free the pointer returned.
+   * @note The caller must free the pointer returned by this function.
    *
    * @param   handle        Management handle.
    *
-   * @return                Cluster state (or NULL on error).
+   * @return                Cluster state (or <var>NULL</var> on error).
    */
   struct ndb_mgm_cluster_state * ndb_mgm_get_status(NdbMgmHandle handle);
 
@@ -643,36 +644,36 @@ extern "C" {
    */
 
   /**
-   * Stop database nodes
+   * Stops database nodes
    *
    * @param   handle        Management handle.
-   * @param   no_of_nodes   no of database nodes<br>
-   *                        0 - means all database nodes in cluster<br>
-   *                        n - Means stop n node(s) specified in the
+   * @param   no_of_nodes   Number of database nodes to be stopped<br>
+   *                          0: All database nodes in cluster<br>
+   *                          n: Stop the <var>n</var> node(s) specified in the
    *                            array node_list
-   * @param   node_list     List of node ids of database nodes to be stopped
+   * @param   node_list     List of node IDs for database nodes to be stopped
    *
-   * @return                No of nodes stopped (or -1 on error)
+   * @return                Number of nodes stopped (-1 on error)
    *
-   * @note    The function is equivalent
-   *          to ndb_mgm_stop2(handle, no_of_nodes, node_list, 0)
+   * @note    This function is equivalent
+   *          to calling ndb_mgm_stop2(handle, no_of_nodes, node_list, 0)
    */
   int ndb_mgm_stop(NdbMgmHandle handle, int no_of_nodes,
 		   const int * node_list);
 
   /**
-   * Stop database nodes
+   * Stops database nodes
    *
    * @param   handle        Management handle.
-   * @param   no_of_nodes   No of database nodes<br>
-   *                        0 - means all database nodes in cluster<br>
-   *                        n - Means stop n node(s) specified in
+   * @param   no_of_nodes   Number of database nodes to stop<br>
+   *                          0: All database nodes in cluster<br>
+   *                          n: Stop the <var>n</var> node(s) specified in
    *                            the array node_list
-   * @param   node_list     List of node ids of database nodes to be stopped
-   * @param   abort         Don't perform gracefull stop,
-   *                        but rather stop immediatly
+   * @param   node_list     List of node IDs of database nodes to be stopped
+   * @param   abort         Don't perform graceful stop,
+   *                        but rather stop immediately
    *
-   * @return                No of nodes stopped (or -1 on error).
+   * @return                Number of nodes stopped (-1 on error).
    */
   int ndb_mgm_stop2(NdbMgmHandle handle, int no_of_nodes,
 		    const int * node_list, int abort);
@@ -681,15 +682,15 @@ extern "C" {
    * Restart database nodes
    *
    * @param   handle        Management handle.
-   * @param   no_of_nodes   No of database nodes<br>
-   *                        0 - means all database nodes in cluster<br>
-   *                        n - Means stop n node(s) specified in the
+   * @param   no_of_nodes   Number of database nodes to restart<br>
+   *                          0: All database nodes in cluster<br>
+   *                          n: Restart the <var>n</var> node(s) specified in the
    *                            array node_list
-   * @param   node_list     List of node ids of database nodes to be stopped
+   * @param   node_list     List of node IDs of database nodes to be restarted
    *
-   * @return                No of nodes stopped (or -1 on error).
+   * @return                Number of nodes restarted (-1 on error).
    *
-   * @note    The function is equivalent to
+   * @note    This function is equivalent to calling
    *          ndb_mgm_restart2(handle, no_of_nodes, node_list, 0, 0, 0);
    */
   int ndb_mgm_restart(NdbMgmHandle handle, int no_of_nodes,
@@ -699,18 +700,18 @@ extern "C" {
    * Restart database nodes
    *
    * @param   handle        Management handle.
-   * @param   no_of_nodes   No of database nodes<br>
-   *                        0 - means all database nodes in cluster<br>
-   *                        n - Means stop n node(s) specified in the
+   * @param   no_of_nodes   Number of database nodes to be restarted:<br>
+   *                          0: Restart all database nodes in the cluster<br>
+   *                          n: Restart the <var>n</var> node(s) specified in the
    *                            array node_list
-   * @param   node_list     List of node ids of database nodes to be stopped
-   * @param   initial       Remove filesystem from node(s) restarting
+   * @param   node_list     List of node IDs of database nodes to be restarted
+   * @param   initial       Remove filesystem from restarting node(s)
    * @param   nostart       Don't actually start node(s) but leave them
    *                        waiting for start command
-   * @param   abort         Don't perform gracefull restart,
-   *                        but rather restart immediatly
+   * @param   abort         Don't perform graceful restart,
+   *                        but rather restart immediately
    *
-   * @return                No of nodes stopped (or -1 on error).
+   * @return                Number of nodes stopped (-1 on error).
    */
   int ndb_mgm_restart2(NdbMgmHandle handle, int no_of_nodes,
 		       const int * node_list, int initial,
@@ -720,19 +721,19 @@ extern "C" {
    * Start database nodes
    *
    * @param   handle        Management handle.
-   * @param   no_of_nodes   No of database nodes<br>
-   *                        0 - means all database nodes in cluster<br>
-   *                        n - Means start n node(s) specified in
+   * @param   no_of_nodes   Number of database nodes to be started<br>
+   *                        0: Start all database nodes in the cluster<br>
+   *                        n: Start the <var>n</var> node(s) specified in
    *                            the array node_list
-   * @param   node_list     List of node ids of database nodes to be started
+   * @param   node_list     List of node IDs of database nodes to be started
    *
-   * @return                No of nodes started (or -1 on error).
+   * @return                Number of nodes actually started (-1 on error).
    *
-   * @note    The nodes to start must have been started with nostart(-n)
+   * @note    The nodes to be started must have been started with nostart(-n)
    *          argument.
    *          This means that the database node binary is started and
    *          waiting for a START management command which will
-   *          actually start the database node functionality
+   *          actually enable the database node
    */
   int ndb_mgm_start(NdbMgmHandle handle,
 		    int no_of_nodes,
@@ -749,7 +750,7 @@ extern "C" {
    *
    * @param   handle        NDB management handle.
    * @param   level         A cluster log level to filter.
-   * @param   enable        set 1=enable 0=disable
+   * @param   enable        Set 1=enable or 0=disable
    * @param   reply         Reply message.
    *
    * @return                -1 on error.
@@ -766,13 +767,13 @@ extern "C" {
    *
    * @return                A vector of seven elements,
    *                        where each element contains
-   *                        1 if a severity is enabled and 0 if not.
-   *                        A severity is stored at position
-   *                        ndb_mgm_clusterlog_level,
+   *                        1 if a severity indicator is enabled and 0 if not.
+   *                        A severity level is stored at position
+   *                        ndb_mgm_clusterlog_level;
    *                        for example the "error" level is stored in position
    *                        [NDB_MGM_CLUSTERLOG_ERROR-1].
    *                        The first element in the vector signals
-   *                        whether the clusterlog
+   *                        whether the cluster log
    *                        is disabled or enabled.
    */
   unsigned int *ndb_mgm_get_logfilter(NdbMgmHandle handle);
@@ -781,7 +782,7 @@ extern "C" {
    * Set log category and levels for the cluster log
    *
    * @param   handle        NDB management handle.
-   * @param   nodeId        Node id.
+   * @param   nodeId        Node ID.
    * @param   category      Event category.
    * @param   level         Log level (0-15).
    * @param   reply         Reply message.
@@ -796,10 +797,10 @@ extern "C" {
   /**
    * Listen to log events
    *
-   * @param filter pairs of { level, ndb_mgm_event_category } that will be
-   *        pushed to fd, level=0 ends lists
+   * @param   filter        pairs of { level, ndb_mgm_event_category } that will be
+   *                        pushed to fd, level=0 ends lists
    *
-   * @return fd which events will be pushed to
+   * @return  fd            which events will be pushed to the log
    */
   int ndb_mgm_listen_event(NdbMgmHandle handle, int filter[]);
 
@@ -808,7 +809,7 @@ extern "C" {
    * Set log category and levels for the Node
    *
    * @param   handle        NDB management handle.
-   * @param   nodeId        Node id.
+   * @param   nodeId        Node ID.
    * @param   category      Event category.
    * @param   level         Log level (0-15).
    * @param   reply         Reply message.
@@ -840,13 +841,13 @@ extern "C" {
   /**
    * Start backup
    *
-   * @param   handle        NDB management handle.
-   * @param   wait_completed 0=don't wait for confirmation,
-   *                         1=wait for backup started,
-   *                         2=wait for backup completed
-   * @param   backup_id     Backup id is returned from function.
-   * @param   reply         Reply message.
-   * @return                -1 on error.
+   * @param   handle          NDB management handle.
+   * @param   wait_completed  0:  Don't wait for confirmation<br>
+   *                          1:  Wait for backup to be started<br>
+   *                          2:  Wait for backup to be completed
+   * @param   backup_id       Backup ID is returned from function.
+   * @param   reply           Reply message.
+   * @return                  -1 on error.
    */
   int ndb_mgm_start_backup(NdbMgmHandle handle, int wait_completed,
 			   unsigned int* backup_id,
@@ -856,7 +857,7 @@ extern "C" {
    * Abort backup
    *
    * @param   handle        NDB management handle.
-   * @param   backup_id     Backup Id.
+   * @param   backup_id     Backup ID.
    * @param   reply         Reply message.
    * @return                -1 on error.
    */
@@ -874,7 +875,7 @@ extern "C" {
    * Enter Single user mode
    *
    * @param   handle        NDB management handle.
-   * @param   nodeId        Node Id of the single user node
+   * @param   nodeId        Node ID of the single user node
    * @param   reply         Reply message.
    * @return                -1 on error.
    */
@@ -885,7 +886,7 @@ extern "C" {
    * Exit Single user mode
    *
    * @param   handle        NDB management handle.
-   * @param   nodeId        Node Id of the single user node
+   * @param   nodeId        Node ID of the single user node
    * @param   reply         Reply message.
    *
    * @return                -1 on error.
@@ -904,11 +905,11 @@ extern "C" {
    * Get configuration
    * @param   handle     NDB management handle.
    * @param   version    Version of configuration, 0 means latest
-   *                     (which is the only supported input at this point)
+   *                     (Currently this is the only supported value for this parameter)
    *
    * @return configuration
    *
-   * @note the caller must call ndb_mgm_destroy_configuration()
+   * @note The caller is responsible for calling ndb_mgm_destroy_configuration()
    */
   struct ndb_mgm_configuration * ndb_mgm_get_configuration(NdbMgmHandle handle,
 							   unsigned version);

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,