BUG#41924: high-level replication functions are not commented

Adding comments to some of the high-level functions in replication.

sql/log_event.h

@@ -327,18 +327,16 @@ struct sql_ex_info
 #define Q_CHARSET_DATABASE_CODE 8
 
 #define Q_TABLE_MAP_FOR_UPDATE_CODE 9
-/* Intvar event post-header */
 
+/* Intvar event data */
 #define I_TYPE_OFFSET        0
 #define I_VAL_OFFSET         1
 
-/* Rand event post-header */
+/* Rand event data */
-
 #define RAND_SEED1_OFFSET 0
 #define RAND_SEED2_OFFSET 8
 
-/* User_var event post-header */
+/* User_var event data */
-
 #define UV_VAL_LEN_SIZE        4
 #define UV_VAL_IS_NULL         1
 #define UV_VAL_TYPE_SIZE       1
@@ -346,7 +344,6 @@ struct sql_ex_info
 #define UV_CHARSET_NUMBER_SIZE 4
 
 /* Load event post-header */
-
 #define L_THREAD_ID_OFFSET   0
 #define L_EXEC_TIME_OFFSET   4
 #define L_SKIP_LINES_OFFSET  8
@@ -357,7 +354,6 @@ struct sql_ex_info
 #define L_DATA_OFFSET        LOAD_HEADER_LEN
 
 /* Rotate event post-header */
-
 #define R_POS_OFFSET       0
 #define R_IDENT_OFFSET     8
 
@@ -2214,10 +2210,11 @@ protected:
 
   @section Intvar_log_event_binary_format Binary Format
 
-  The Post-Header has two components:
+  The Post-Header for this event type is empty.  The Body has two
+  components:
 
   <table>
-  <caption>Post-Header for Intvar_log_event</caption>
+  <caption>Body for Intvar_log_event</caption>
 
   <tr>
     <th>Name</th>
@@ -2291,11 +2288,12 @@ private:
   which are stored internally as two 64-bit numbers.
 
   @section Rand_log_event_binary_format Binary Format  
-  This event type has no Post-Header. The Body of this event type has
+
-  two components:
+  The Post-Header for this event type is empty.  The Body has two
+  components:
 
   <table>
-  <caption>Post-Header for Intvar_log_event</caption>
+  <caption>Body for Rand_log_event</caption>
 
   <tr>
     <th>Name</th>

sql/repl_failsafe.cc

@@ -644,6 +644,16 @@ err:
 }
 #endif
 
+
+/**
+  Execute a SHOW SLAVE HOSTS statement.
+
+  @param thd Pointer to THD object for the client thread executing the
+  statement.
+
+  @retval FALSE success
+  @retval TRUE failure
+*/
 bool show_slave_hosts(THD* thd)
 {
   List<Item> field_list;

sql/slave.cc

@@ -1357,6 +1357,17 @@ int register_slave_on_master(MYSQL* mysql, Master_info *mi,
 }
 
 
+/**
+  Execute a SHOW SLAVE STATUS statement.
+
+  @param thd Pointer to THD object for the client thread executing the
+  statement.
+
+  @param mi Pointer to Master_info object for the IO thread.
+
+  @retval FALSE success
+  @retval TRUE failure
+*/
 bool show_master_info(THD* thd, Master_info* mi)
 {
   // TODO: fix this for multi-master
@@ -2062,7 +2073,7 @@ int apply_event_and_update_pos(Log_event* ev, THD* thd, Relay_log_info* rli,
      fewer times, 0 is returned.
 
    - init_master_info or init_relay_log_pos failed. (These are called
-     if a failure occurs when applying the event.)</li>
+     if a failure occurs when applying the event.)
 
    - An error occurred when updating the binlog position.
 
@@ -2307,8 +2318,14 @@ static int try_to_reconnect(THD *thd, MYSQL *mysql, Master_info *mi,
 }
 
 
-/* Slave I/O Thread entry point */
+/**
+  Slave IO thread entry point.
 
+  @param arg Pointer to Master_info struct that holds information for
+  the IO thread.
+
+  @return Always 0.
+*/
 pthread_handler_t handle_slave_io(void *arg)
 {
   THD *thd; // needs to be first for thread_stack
@@ -2616,8 +2633,14 @@ err:
 }
 
 
-/* Slave SQL Thread entry point */
+/**
+  Slave SQL thread entry point.
 
+  @param arg Pointer to Relay_log_info object that holds information
+  for the SQL thread.
+
+  @return Always 0.
+*/
 pthread_handler_t handle_slave_sql(void *arg)
 {
   THD *thd;                     /* needs to be first for thread_stack */
@@ -3710,6 +3733,16 @@ static IO_CACHE *reopen_relay_log(Relay_log_info *rli, const char **errmsg)
 }
 
 
+/**
+  Reads next event from the relay log.  Should be called from the
+  slave IO thread.
+
+  @param rli Relay_log_info structure for the slave IO thread.
+
+  @return The event read, or NULL on error.  If an error occurs, the
+  error is reported through the sql_print_information() or
+  sql_print_error() functions.
+*/
 static Log_event* next_event(Relay_log_info* rli)
 {
   Log_event* ev;

sql/sql_binlog.cc

@@ -18,7 +18,7 @@
 #include "base64.h"
 
 /**
-  Execute a BINLOG statement
+  Execute a BINLOG statement.
 
   To execute the BINLOG command properly the server needs to know
   which format the BINLOG command's event is in.  Therefore, the first
@@ -26,6 +26,9 @@
   Format_description_log_event, as outputted by mysqlbinlog.  This
   Format_description_log_event is cached in
   rli->description_event_for_exec.
+
+  @param thd Pointer to THD object for the client thread executing the
+  statement.
 */
 
 void mysql_client_binlog_statement(THD* thd)

sql/sql_lex.h

@@ -190,6 +190,15 @@ typedef struct st_lex_server_options
   char *server_name, *host, *db, *username, *password, *scheme, *socket, *owner;
 } LEX_SERVER_OPTIONS;
 
+
+/**
+  Structure to hold parameters for CHANGE MASTER or START/STOP SLAVE
+  or SHOW NEW MASTER.
+
+  Remark: this should not be confused with Master_info (and perhaps
+  would better be renamed to st_lex_replication_info).  Some fields,
+  e.g., delay, are saved in Relay_log_info, not in Master_info.
+*/
 typedef struct st_lex_master_info
 {
   char *host, *user, *password, *log_file_name;

sql/sql_repl.cc

@@ -257,6 +257,17 @@ bool purge_error_message(THD* thd, int res)
 }
 
 
+/**
+  Execute a PURGE BINARY LOGS TO <log> command.
+
+  @param thd Pointer to THD object for the client thread executing the
+  statement.
+
+  @param to_log Name of the last log to purge.
+
+  @retval FALSE success
+  @retval TRUE failure
+*/
 bool purge_master_logs(THD* thd, const char* to_log)
 {
   char search_file_name[FN_REFLEN];
@@ -273,6 +284,17 @@ bool purge_master_logs(THD* thd, const char* to_log)
 }
 
 
+/**
+  Execute a PURGE BINARY LOGS BEFORE <date> command.
+
+  @param thd Pointer to THD object for the client thread executing the
+  statement.
+
+  @param purge_time Date before which logs should be purged.
+
+  @retval FALSE success
+  @retval TRUE failure
+*/
 bool purge_master_logs_before_date(THD* thd, time_t purge_time)
 {
   if (!mysql_bin_log.is_open())
@@ -765,6 +787,20 @@ err:
   DBUG_VOID_RETURN;
 }
 
+
+/**
+  Execute a START SLAVE statement.
+
+  @param thd Pointer to THD object for the client thread executing the
+  statement.
+
+  @param mi Pointer to Master_info object for the slave's IO thread.
+
+  @param net_report If true, saves the exit status into thd->main_da.
+
+  @retval 0 success
+  @retval 1 error
+*/
 int start_slave(THD* thd , Master_info* mi,  bool net_report)
 {
   int slave_errno= 0;
@@ -890,6 +926,19 @@ int start_slave(THD* thd , Master_info* mi,  bool net_report)
 }
 
 
+/**
+  Execute a STOP SLAVE statement.
+
+  @param thd Pointer to THD object for the client thread executing the
+  statement.
+
+  @param mi Pointer to Master_info object for the slave's IO thread.
+
+  @param net_report If true, saves the exit status into thd->main_da.
+
+  @retval 0 success
+  @retval 1 error
+*/
 int stop_slave(THD* thd, Master_info* mi, bool net_report )
 {
   DBUG_ENTER("stop_slave");
@@ -942,20 +991,17 @@ int stop_slave(THD* thd, Master_info* mi, bool net_report )
 }
 
 
-/*
+/**
-  Remove all relay logs and start replication from the start
+  Execute a RESET SLAVE statement.
 
-  SYNOPSIS
+  @param thd Pointer to THD object of the client thread executing the
-    reset_slave()
+  statement.
-    thd			Thread handler
-    mi			Master info for the slave
 
-  RETURN
+  @param mi Pointer to Master_info object for the slave.
-    0	ok
+
-    1	error
+  @retval 0 success
+  @retval 1 error
 */
-
-
 int reset_slave(THD *thd, Master_info* mi)
 {
   MY_STAT stat_area;
@@ -1070,6 +1116,18 @@ void kill_zombie_dump_threads(uint32 slave_server_id)
 }
 
 
+/**
+  Execute a CHANGE MASTER statement.
+
+  @param thd Pointer to THD object for the client thread executing the
+  statement.
+
+  @param mi Pointer to Master_info object belonging to the slave's IO
+  thread.
+
+  @retval FALSE success
+  @retval TRUE error
+*/
 bool change_master(THD* thd, Master_info* mi)
 {
   int thread_mask;
@@ -1283,6 +1341,16 @@ bool change_master(THD* thd, Master_info* mi)
   DBUG_RETURN(FALSE);
 }
 
+
+/**
+  Execute a RESET MASTER statement.
+
+  @param thd Pointer to THD object of the client thread executing the
+  statement.
+
+  @retval 0 success
+  @retval 1 error
+*/
 int reset_master(THD* thd)
 {
   if (!mysql_bin_log.is_open())
@@ -1312,6 +1380,15 @@ int cmp_master_pos(const char* log_file_name1, ulonglong log_pos1,
 }
 
 
+/**
+  Execute a SHOW BINLOG EVENTS statement.
+
+  @param thd Pointer to THD object for the client thread executing the
+  statement.
+
+  @retval FALSE success
+  @retval TRUE failure
+*/
 bool mysql_show_binlog_events(THD* thd)
 {
   Protocol *protocol= thd->protocol;
@@ -1462,6 +1539,15 @@ err:
 }
 
 
+/**
+  Execute a SHOW MASTER STATUS statement.
+
+  @param thd Pointer to THD object for the client thread executing the
+  statement.
+
+  @retval FALSE success
+  @retval TRUE failure
+*/
 bool show_binlog_info(THD* thd)
 {
   Protocol *protocol= thd->protocol;
@@ -1495,18 +1581,15 @@ bool show_binlog_info(THD* thd)
 }
 
 
-/*
+/**
-  Send a list of all binary logs to client
+  Execute a SHOW BINARY LOGS statement.
 
-  SYNOPSIS
+  @param thd Pointer to THD object for the client thread executing the
-    show_binlogs()
+  statement.
-    thd		Thread specific variable
 
-  RETURN VALUES
+  @retval FALSE success
-    FALSE OK
+  @retval TRUE failure
-    TRUE  error
 */
-
 bool show_binlogs(THD* thd)
 {
   IO_CACHE *index_file;