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

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

sql/log_event.h:
  Fixed some mistakes in comments.
sql/repl_failsafe.cc:
  Added comment for show_slave_hosts()
sql/slave.cc:
  Added comment for show_master_info(), handle_slave_[sql|io](), and next_event()
sql/sql_binlog.cc:
  Added @param comment.
sql/sql_lex.h:
  Added comment for st_lex_master_info.
sql/sql_repl.cc:
  Added comments for functions executing a statement:
      PURGE BINARY LOGS
      START SLAVE
      STOP SLAVE
      RESET SLAVE
      CHANGE MASTER
      RESET MASTER
      SHOW BINLOG EVENTS
      SHOW MASTER STATUS
      SHOW BINARY LOGS

1 files changed, 36 insertions, 3 deletions

diff --git a/sql/slave.cc b/sql/slave.cc
index 43b70f29a68..22c61b3ec6c 100644
--- a/sql/slave.cc
+++ b/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;