WL#4078: Document binary format of binlog entries

Minor update with corrections and notes on the binlog format.
This only affects comments, not code.


sql/log_event.h:
  Fixes in documentation of binlog format.

1 files changed, 26 insertions, 20 deletions

diff --git a/sql/log_event.h b/sql/log_event.h
index 4e151d6cde9..c46827253a3 100644
--- a/sql/log_event.h
+++ b/sql/log_event.h
@@ -670,18 +670,18 @@ typedef struct st_print_event_info
   Any @c Log_event saved on disk consists of the following three
   components.
 
-  * Common-Header
-  * Post-Header
-  * Body
+  - Common-Header
+  - Post-Header
+  - Body
 
   The Common-Header, documented in the table @ref Table_common_header
   "below", always has the same form and length within one version of
-  MySQL.  Each event type specifies a form and length of the
-  Post-Header common to all events of the type.  The Body may be of
-  different form and length even for different events of the same
-  type.  The binary formats of Post-Header and Body are documented
-  separately in each subclass.  The binary format of Common-Header is
-  as follows.
+  MySQL.  Each event type specifies a format and length of the
+  Post-Header.  The length of the Common-Header is the same for all
+  events of the same type.  The Body may be of different format and
+  length even for different events of the same type.  The binary
+  formats of Post-Header and Body are documented separately in each
+  subclass.  The binary format of Common-Header is as follows.
 
   <table>
   <caption>Common-Header</caption>
@@ -750,8 +750,8 @@ typedef struct st_print_event_info
   - Some events use a special format for efficient representation of
   unsigned integers, called Packed Integer.  A Packed Integer has the
   capacity of storing up to 8-byte integers, while small integers
-  still can use 1, 3, or 4 bytes.  The first byte indicates how many
-  bytes are used by the integer, according to the following table:
+  still can use 1, 3, or 4 bytes.  The value of the first byte
+  determines how to read the number, according to the following table:
 
   <table>
   <caption>Format of Packed Integer</caption>
@@ -763,7 +763,7 @@ typedef struct st_print_event_info
 
   <tr>
     <td>0-250</td>
-    <td>The first byte is the number (in range 0-250), and no more
+    <td>The first byte is the number (in the range 0-250), and no more
     bytes are used.</td>
   </tr>
 
@@ -1174,6 +1174,10 @@ protected:
 
   @section Query_log_event_binary_format Binary format
 
+  See @ref Log_event_binary_format "Binary format for log events" for
+  a general discussion and introduction to the binary format of binlog
+  events.
+
   The Post-Header has five components:
 
   <table>
@@ -1407,7 +1411,7 @@ protected:
     query "SELECT id, character_set_name, collation_name FROM
     COLLATIONS".
 
-    Cf. Q_CHARSET_DATABASE_NUMBER below.
+    Cf. Q_CHARSET_DATABASE_CODE below.
 
     This field is always written.
     </td>
@@ -1442,7 +1446,7 @@ protected:
 
   <tr>
     <td>charset_database_number</td>
-    <td>Q_CHARSET_DATABASE_NUMBER == 8</td>
+    <td>Q_CHARSET_DATABASE_CODE == 8</td>
     <td>2 byte integer</td>
 
     <td>The value of the collation_database system variable (in the
@@ -1457,11 +1461,11 @@ protected:
 
     In newer versions, "CREATE TABLE" has been changed to take the
     character set from the database of the created table, rather than
-    the database of the current database.  This makes a difference
-    when creating a table in another database than the current one.
-    "LOAD DATA INFILE" has not yet changed to do this, but there are
-    plans to eventually do it, and to make collation_database
-    read-only.
+    the character set of the current database.  This makes a
+    difference when creating a table in another database than the
+    current one.  "LOAD DATA INFILE" has not yet changed to do this,
+    but there are plans to eventually do it, and to make
+    collation_database read-only.
 
     This field is written if it is not 0.
     </td>
@@ -1480,7 +1484,7 @@ protected:
   Q_CATALOG_CODE will never be written by a new master, but can still
   be understood by a new slave.
 
-  * See Q_CHARSET_DATABASE_NUMBER in the table above.
+  * See Q_CHARSET_DATABASE_CODE in the table above.
 
 */
 class Query_log_event: public Log_event
@@ -1919,6 +1923,8 @@ private:
 
   @subsection Load_log_event_notes_on_previous_versions Notes on Previous Versions
 
+  This event type is understood by current versions, but only
+  generated by MySQL 3.23 and earlier.
 */
 class Load_log_event: public Log_event
 {