Add missing comment blocks.

server/modules/routing/readwritesplit/readwritesplit.c

@@ -1511,6 +1511,12 @@ backend_ref_t *get_bref_from_dcb(ROUTER_CLIENT_SES *rses, DCB *dcb)
  * 
  * Calls hang-up function for DCB if it is not both running and in
  * master/slave/joined/ndb role. Called by DCB's callback routine.
+ * 
+ * @param dcb       DCB relating to a backend server
+ * @param reason    The reason for the state change
+ * @param data      Data is a backend reference structure belonging to this router
+ * 
+ * @return  1 for success, 0 for failure
  */
 int router_handle_state_switch(DCB *dcb, DCB_REASON reason, void *data)
 {
@@ -1668,6 +1674,14 @@ static bool rwsplit_process_router_options(ROUTER_INSTANCE *router,
     return success;
 }
 
+/**
+ * @brief Handle an error reply for a client
+ *
+ * @param ses           Session
+ * @param rses          Router session
+ * @param backend_dcb   DCB for the backend server that has failed
+ * @param errmsg        GWBUF containing the error message
+ */
 static void handle_error_reply_client(SESSION *ses, ROUTER_CLIENT_SES *rses,
                                       DCB *backend_dcb, GWBUF *errmsg)
 {
@@ -1801,6 +1815,13 @@ return_succp:
     return succp;
 }
 
+/**
+ * @brief Calculate the number of backend servers
+ *
+ * @param inst      Router instance
+ *
+ * @return int - count of servers
+ */
 static int router_get_servercount(ROUTER_INSTANCE *inst)
 {
     int router_nservers = 0;
@@ -1814,6 +1835,16 @@ static int router_get_servercount(ROUTER_INSTANCE *inst)
     return router_nservers;
 }
 
+/**
+ * @brief Calculate whether we have enough servers to route a query
+ *
+ * @param p_rses        Router session
+ * @param min_nsrv      Minimum number of servers that is sufficient
+ * @param nsrv          Actual number of servers
+ * @param router        Router instance
+ *
+ * @return bool - whether enough, side effect is error logging
+ */
 static bool have_enough_servers(ROUTER_CLIENT_SES **p_rses, const int min_nsrv,
                                 int router_nsrv, ROUTER_INSTANCE *router)
 {

server/modules/routing/readwritesplit/rwsplit_mysql.c

@@ -60,8 +60,26 @@
  */
 
 /* This could be placed in the protocol, with a new API entry point
- * It is certainly MySQL specific.
+ * It is certainly MySQL specific. Packet types are DB specific, but can be
- *  */
+ * assumed to be enums, which can be handled as integers without knowing
+ * which DB is involved until the packet type needs to be interpreted.
+ * 
+ */
+
+/**
+ * @brief Determine packet type
+ *
+ * Examine the packet in the buffer to extract the type, if possible. At the
+ * same time set the second parameter to indicate whether the packet was
+ * empty.
+ * 
+ * It is assumed that the packet length and type are contained within a single
+ * buffer, the one indicated by the first parameter.
+ * 
+ * @param querybuf  Buffer containing the packet
+ * @param non_empty_packet  bool indicating whether the packet is non-empty
+ * @return The packet type, or MYSQL_COM_UNDEFINED; also the second parameter is set
+ */
 int
 determine_packet_type(GWBUF *querybuf, bool *non_empty_packet)
 {
@@ -85,6 +103,17 @@ determine_packet_type(GWBUF *querybuf, bool *non_empty_packet)
 /*
  * This appears to be MySQL specific
  */
+/**
+ * @brief Determine if a packet contains a SQL query
+ *
+ * Packet type tells us this, but in a DB specific way. This function is
+ * provided so that code that is not DB specific can find out whether a packet
+ * contains a SQL query. Clearly, to be effective different functions must be
+ * called for different DB types.
+ * 
+ * @param packet_type   Type of packet (integer)
+ * @return bool indicating whether packet contains a SQL query
+ */
 bool
 is_packet_a_query(int packet_type)
 {
@@ -94,6 +123,17 @@ is_packet_a_query(int packet_type)
 /*
  * This looks MySQL specific
  */
+/**
+ * @brief Determine if a packet contains a one way message
+ *
+ * Packet type tells us this, but in a DB specific way. This function is
+ * provided so that code that is not DB specific can find out whether a packet
+ * contains a one way messsage. Clearly, to be effective different functions must be
+ * called for different DB types.
+ * 
+ * @param packet_type   Type of packet (integer)
+ * @return bool indicating whether packet contains a one way message
+ */
 bool
 is_packet_a_one_way_message(int packet_type)
 {
@@ -105,6 +145,17 @@ is_packet_a_one_way_message(int packet_type)
  * This one is problematic because it is MySQL specific, but also router
  * specific.
  */
+/**
+ * @brief Log the transaction status
+ *
+ * The router session and the query buffer are used to log the transaction
+ * status, along with the query type (which is a generic description that
+ * should be usable across all DB types).
+ * 
+ * @param rses      Router session
+ * @param querybuf  Query buffer
+ * @param qtype     Query type
+ */
 void
 log_transaction_status(ROUTER_CLIENT_SES *rses, GWBUF *querybuf, qc_query_type_t qtype)
 {
@@ -140,6 +191,23 @@ log_transaction_status(ROUTER_CLIENT_SES *rses, GWBUF *querybuf, qc_query_type_t
  * utility to convert packet type to a string. The aim is for most of this
  * code to remain as part of the router.
  */
+/**
+ * @brief Operations to be carried out if request is for all backend servers
+ *
+ * If the choice of sending to all backends is in conflict with other bit
+ * settings in route_target, then error messages are written to the log.
+ * 
+ * Otherwise, the function route_session_write is called to carry out the
+ * actual routing.
+ * 
+ * @param route_target  Bit map indicating where packet should be routed
+ * @param inst          Router instance
+ * @param rses          Router session
+ * @param querybuf      Query buffer containing packet
+ * @param packet_type   Integer (enum) indicating type of packet
+ * @param qtype         Query type 
+ * @return bool indicating whether the session can continue
+ */
 bool
 handle_target_is_all(route_target_t route_target,
         ROUTER_INSTANCE *inst, ROUTER_CLIENT_SES *rses,
@@ -218,6 +286,15 @@ handle_target_is_all(route_target_t route_target,
 }
 
 /* This is MySQL specific */
+/**
+ * @brief Write an error message to the log indicating failure
+ * 
+ * Used when an attempt to lock the router session fails.
+ *
+ * @param querybuf      Query buffer containing packet
+ * @param packet_type   Integer (enum) indicating type of packet
+ * @param qtype         Query type 
+ */
 void
 session_lock_failure_handling(GWBUF *querybuf, int packet_type, qc_query_type_t qtype)
 {
@@ -237,6 +314,14 @@ session_lock_failure_handling(GWBUF *querybuf, int packet_type, qc_query_type_t
 /*
  * Probably MySQL specific because of modutil function
  */
+/**
+ * @brief Write an error message to the log for closed session
+ * 
+ * This happens if a request is received for a session that is already
+ * closing down.
+ *
+ * @param querybuf      Query buffer containing packet
+ */
 void closed_session_reply(GWBUF *querybuf)
 {
     uint8_t* data = GWBUF_DATA(querybuf);
@@ -254,6 +339,15 @@ void closed_session_reply(GWBUF *querybuf)
 /*
  * Probably MySQL specific because of modutil function
  */
+/**
+ * @brief First step to handle request in a live session
+ * 
+ * Used when a request is about to be routed. Note that the query buffer is 
+ * passed by name and is likely to be modified by this function.
+ *
+ * @param querybuf      Query buffer containing packet
+ * @param rses          Router session
+ */
 void live_session_reply(GWBUF **querybuf, ROUTER_CLIENT_SES *rses)
 {
     GWBUF *tmpbuf = *querybuf;
@@ -276,6 +370,16 @@ void live_session_reply(GWBUF **querybuf, ROUTER_CLIENT_SES *rses)
 /*
  * Uses MySQL specific mechanisms
  */
+/**
+ * @brief Write an error message to the log for session lock failure
+ * 
+ * This happens when processing a client reply and the session cannot be
+ * locked.
+ *
+ * @param rses          Router session
+ * @param buf           Query buffer containing reply data
+ * @param dcb           The backend DCB that sent the reply
+ */
 void print_error_packet(ROUTER_CLIENT_SES *rses, GWBUF *buf, DCB *dcb)
 {
 #if defined(SS_DEBUG)
@@ -326,6 +430,15 @@ void print_error_packet(ROUTER_CLIENT_SES *rses, GWBUF *buf, DCB *dcb)
 /*
  * Uses MySQL specific mechanisms
  */
+/**
+ * @brief Check the reply from a backend server to a session command
+ * 
+ * If the reply is an error, a message may be logged.
+ *
+ * @param writebuf      Query buffer containing reply data
+ * @param scur          Session cursor
+ * @param bref          Router session data for a backend server
+ */
 void check_session_command_reply(GWBUF *writebuf, sescmd_cursor_t *scur, backend_ref_t *bref)
 {
         if (MXS_LOG_PRIORITY_IS_ENABLED(LOG_ERR) &&
@@ -349,7 +462,7 @@ void check_session_command_reply(GWBUF *writebuf, sescmd_cursor_t *scur, backend
 }
 
 /**
- * If session command cursor is passive, sends the command to backend for
+ * @brief If session command cursor is passive, sends the command to backend for
  * execution.
  *
  * Returns true if command was sent or added successfully to the queue.
@@ -357,6 +470,9 @@ void check_session_command_reply(GWBUF *writebuf, sescmd_cursor_t *scur, backend
  *  commands.
  *
  * Router session must be locked.
+ * 
+ * @param backend_ref   Router session backend database data
+ * @return bool - true for success, false for failure
  */
 /*
  * Uses MySQL specific values in the large switch statement, although it

server/modules/routing/readwritesplit/rwsplit_route_stmt.c

@@ -424,6 +424,14 @@ return_succp:
     return succp;
 }
 
+/**
+ * @brief Function to hash keys in read-write split router
+ * 
+ * Used to store information about temporary tables.
+ *
+ * @param key   key to be hashed, actually a character string
+ * @result      the hash value integer
+ */
 int rwsplit_hashkeyfun(const void *key)
 {
     if (key == NULL)
@@ -441,6 +449,15 @@ int rwsplit_hashkeyfun(const void *key)
     return hash;
 }
 
+/**
+ * @brief Function to compare hash keys in read-write split router
+ * 
+ * Used to manage information about temporary tables.
+ *
+ * @param key   first key to be compared, actually a character string
+ * @param v2    second key to be compared, actually a character string
+ * @result      1 if keys are equal, 0 otherwise
+ */
 int rwsplit_hashcmpfun(const void *v1, const void *v2)
 {
     const char *i1 = (const char *)v1;
@@ -449,12 +466,27 @@ int rwsplit_hashcmpfun(const void *v1, const void *v2)
     return strcmp(i1, i2);
 }
 
+/**
+ * @brief Function to duplicate a hash value in read-write split router
+ * 
+ * Used to manage information about temporary tables.
+ *
+ * @param fval  value to be duplicated, actually a character string
+ * @result      the duplicated value, actually a character string
+ */
 void *rwsplit_hstrdup(const void *fval)
 {
     char *str = (char *)fval;
     return MXS_STRDUP(str);
 }
 
+/**
+ * @brief Function to free hash values in read-write split router
+ * 
+ * Used to manage information about temporary tables.
+ *
+ * @param key   value to be freed
+ */
 void rwsplit_hfree(void *fval)
 {
     MXS_FREE(fval);
@@ -869,6 +901,16 @@ route_target_t get_route_target(ROUTER_CLIENT_SES *rses,
     return target;
 }
 
+/**
+ * @brief Handle multi statement queries and load statements
+ * 
+ * One of the possible types of handling required when a request is routed
+ *
+ *  @param ses          Router session
+ *  @param querybuf     Buffer containing query to be routed
+ *  @param packet_type  Type of packet (database specific)
+ *  @param qtype        Query type
+ */
 void
 handle_multi_temp_and_load(ROUTER_CLIENT_SES *rses, GWBUF *querybuf,
     int packet_type, int *qtype)
@@ -955,6 +997,18 @@ handle_multi_temp_and_load(ROUTER_CLIENT_SES *rses, GWBUF *querybuf,
         }
 }
 
+/**
+ * @brief Handle hinted target query
+ * 
+ * One of the possible types of handling required when a request is routed
+ *
+ *  @param ses          Router session
+ *  @param querybuf     Buffer containing query to be routed
+ *  @param route_target Target for the query
+ *  @param target_dcb   DCB for the target server
+ * 
+ *  @return bool - true if succeeded, false otherwise
+ */
 bool handle_hinted_target(ROUTER_CLIENT_SES *rses, GWBUF *querybuf,
         route_target_t route_target, DCB **target_dcb)
 {
@@ -1027,6 +1081,17 @@ bool handle_hinted_target(ROUTER_CLIENT_SES *rses, GWBUF *querybuf,
     return succp;
 }
 
+/**
+ * @brief Handle slave is the target
+ * 
+ * One of the possible types of handling required when a request is routed
+ *
+ *  @param inst         Router instance
+ *  @param ses          Router session
+ *  @param target_dcb   DCB for the target server
+ * 
+ *  @return bool - true if succeeded, false otherwise
+ */
 bool handle_slave_is_target(ROUTER_INSTANCE *inst, ROUTER_CLIENT_SES *rses,
         DCB **target_dcb)
 {
@@ -1050,6 +1115,17 @@ bool handle_slave_is_target(ROUTER_INSTANCE *inst, ROUTER_CLIENT_SES *rses,
     }
 }
 
+/**
+ * @brief Handle master is the target
+ * 
+ * One of the possible types of handling required when a request is routed
+ *
+ *  @param inst         Router instance
+ *  @param ses          Router session
+ *  @param target_dcb   DCB for the target server
+ * 
+ *  @return bool - true if succeeded, false otherwise
+ */
 bool handle_master_is_target(ROUTER_INSTANCE *inst, ROUTER_CLIENT_SES *rses,
         DCB **target_dcb)
 {
@@ -1090,6 +1166,18 @@ bool handle_master_is_target(ROUTER_INSTANCE *inst, ROUTER_CLIENT_SES *rses,
     return succp;
 }
 
+/**
+ * @brief Handle got a target
+ * 
+ * One of the possible types of handling required when a request is routed
+ *
+ *  @param inst         Router instance
+ *  @param ses          Router session
+ *  @param querybuf     Buffer containing query to be routed
+ *  @param target_dcb   DCB for the target server
+ * 
+ *  @return bool - true if succeeded, false otherwise
+ */
 bool
 handle_got_target(ROUTER_INSTANCE *inst, ROUTER_CLIENT_SES *rses,
         GWBUF *querybuf, DCB *target_dcb)
@@ -1149,7 +1237,11 @@ handle_got_target(ROUTER_INSTANCE *inst, ROUTER_CLIENT_SES *rses,
 }
 
 /**
- * Create a generic router session property structure.
+ * @brief Create a generic router session property structure.
+ * 
+ * @param prop_type     Property type
+ * 
+ * @return property structure of requested type, or NULL if failed
  */
 rses_property_t *rses_property_init(rses_property_type_t prop_type)
 {
@@ -1171,11 +1263,18 @@ rses_property_t *rses_property_init(rses_property_type_t prop_type)
 }
 
 /**
+ * @brief Add property to the router client session
+ * 
  * Add property to the router_client_ses structure's rses_properties
  * array. The slot is determined by the type of property.
  * In each slot there is a list of properties of similar type.
  *
  * Router client session must be locked.
+ * 
+ * @param rses      Router session
+ * @param prop      Router session property to be added
+ * 
+ * @return -1 on failure, 0 on success
  */
 int rses_property_add(ROUTER_CLIENT_SES *rses, rses_property_t *prop)
 {

server/modules/routing/readwritesplit/rwsplit_tmp_table_multi.c

@@ -44,6 +44,8 @@
  */
 
 /**
+ * @brief Check for dropping of temporary tables
+ * 
  * Check if the query is a DROP TABLE... query and
  * if it targets a temporary table, remove it from the hashtable.
  * @param router_cli_ses Router client session
@@ -351,6 +353,15 @@ bool check_for_multi_stmt(GWBUF *buf, void *protocol, mysql_server_cmd_t packet_
     return rval;
 }
 
+/**
+ * @brief Determine the type of a query
+ * 
+ * @param querybuf      GWBUF containing the query
+ * @param packet_type   Integer denoting DB specific enum
+ * @param non_empty_packet  Boolean to be set by this function
+ * 
+ * @return qc_query_type_t the query type; also the non_empty_packet bool is set
+ */
 qc_query_type_t
 determine_query_type(GWBUF *querybuf, int packet_type, bool non_empty_packet)
 {