MDEV-27902 Some Spider code documentation regarding first_link_idx and remote HANDLER commands

storage/spider/ha_spider.cc

@@ -12918,6 +12918,15 @@ void ha_spider::sync_from_clone_source_base(
   DBUG_VOID_RETURN;
 }
 
+/*
+  Set the initial values for each dbton_handler's first_link_idx and
+  strict_group_by.
+
+  First, reset first_link_idx to -1.
+  Then, for each active remote server, if the corresponding
+  dbton_handler has not been set yet (first_link_idx == -1), set its
+  first_link_idx to be the index of the connection.
+*/
 void ha_spider::set_first_link_idx()
 {
   int roop_count, all_link_idx;
@@ -12957,6 +12966,16 @@ void ha_spider::set_first_link_idx()
   DBUG_VOID_RETURN;
 }
 
+/*
+  Reset the initial values for each dbton_handler's first_link_idx to
+  -1.
+
+  Also, set the search_link_idx'th active server's first_link_idx to
+  search_link_idx.
+
+  search_link_idx is commonly randomly set using
+  spider_conn_first_link_idx - see the commentary of that function.
+*/
 void ha_spider::reset_first_link_idx()
 {
   int all_link_idx;

storage/spider/ha_spider.h

@@ -167,7 +167,13 @@ class ha_spider final : public handler
   ulonglong          *db_request_id;
   uchar              *db_request_phase;
   uchar              *m_handler_opened;
+  /* ids for use in HANDLER command */
   uint               *m_handler_id;
+  /*
+    aliases for use in HANDLER command, in the format of t%5u on
+    m_handler_id. So for example, if m_handler_id is 3, then the
+    corresponding m_handler_cid is t00003
+  */
   char               **m_handler_cid;
 #ifdef HANDLER_HAS_DIRECT_UPDATE_ROWS
   bool               do_direct_update;

storage/spider/spd_db_include.h

@@ -1135,6 +1135,7 @@ class spider_db_handler
   uint dbton_id;
   ha_spider *spider;
   spider_db_share *db_share;
+  /* Index of active server, used in query construction. */
   int first_link_idx;
   bool strict_group_by= false;
   bool no_where_cond= false;

storage/spider/spd_trx.cc

@@ -3933,6 +3933,15 @@ void spider_reuse_trx_ha(
   DBUG_VOID_RETURN;
 }
 
+/**
+  Sets link indices for load balancing read connections
+
+  Assuming `spider->share->link_count` is the number of active servers
+  to use, this function updates `spider->conn_link_idx` with the first
+  server in the same "modulus group" whose link status is not
+  `SPIDER_LINK_STATUS_NG`, or if one cannot be found, use the
+  `link_idx`th server
+*/
 void spider_trx_set_link_idx_for_all(
   ha_spider *spider
 ) {