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, 103 insertions, 20 deletions

diff --git a/sql/sql_repl.cc b/sql/sql_repl.cc
index eac7a50417a..646bfdaefe8 100644
--- a/sql/sql_repl.cc
+++ b/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
-
-  SYNOPSIS
-    reset_slave()
-    thd			Thread handler
-    mi			Master info for the slave
+/**
+  Execute a RESET SLAVE statement.
 
-  RETURN
-    0	ok
-    1	error
-*/
+  @param thd Pointer to THD object of the client thread executing the
+  statement.
 
+  @param mi Pointer to Master_info object for the slave.
 
+  @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
-    show_binlogs()
-    thd		Thread specific variable
+  @param thd Pointer to THD object for the client thread executing the
+  statement.
 
-  RETURN VALUES
-    FALSE OK
-    TRUE  error
+  @retval FALSE success
+  @retval TRUE failure
 */
-
 bool show_binlogs(THD* thd)
 {
   IO_CACHE *index_file;