add comments

Author: kerryjiang

src/SciSharp.MySQL.Replication/ColumnType.cs

@@ -4,38 +4,169 @@
 
 namespace SciSharp.MySQL.Replication
 {
+    /// <summary>
+    /// Represents the MySQL column data types as they appear in the binary log format.
+    /// These values correspond to the type codes used in TABLE_MAP_EVENT to describe table columns.
+    /// </summary>
+    /// <remarks>
+    /// The values match those defined in the MySQL source code in the enum_field_types enumeration,
+    /// which can be found in mysql-server/include/mysql_com.h.
+    /// </remarks>
     public enum ColumnType : byte
     {
+        /// <summary>
+        /// MySQL DECIMAL type (old precision-based format, rarely used).
+        /// </summary>
         DECIMAL = 0,
+        
+        /// <summary>
+        /// MySQL TINY (TINYINT) type, 1-byte integer.
+        /// </summary>
         TINY = 1,
+        
+        /// <summary>
+        /// MySQL SHORT (SMALLINT) type, 2-byte integer.
+        /// </summary>
         SHORT = 2,
+        
+        /// <summary>
+        /// MySQL LONG (INT) type, 4-byte integer.
+        /// </summary>
         LONG = 3,
+        
+        /// <summary>
+        /// MySQL FLOAT type, 4-byte single-precision floating point.
+        /// </summary>
         FLOAT = 4,
+        
+        /// <summary>
+        /// MySQL DOUBLE type, 8-byte double-precision floating point.
+        /// </summary>
         DOUBLE = 5,
+        
+        /// <summary>
+        /// MySQL NULL type, represents NULL values.
+        /// </summary>
         NULL = 6,
+        
+        /// <summary>
+        /// MySQL TIMESTAMP type, represents a point in time.
+        /// </summary>
         TIMESTAMP = 7,
+        
+        /// <summary>
+        /// MySQL LONGLONG (BIGINT) type, 8-byte integer.
+        /// </summary>
         LONGLONG = 8,
+        
+        /// <summary>
+        /// MySQL INT24 (MEDIUMINT) type, 3-byte integer.
+        /// </summary>
         INT24 = 9,
+        
+        /// <summary>
+        /// MySQL DATE type, represents a calendar date.
+        /// </summary>
         DATE = 10,
+        
+        /// <summary>
+        /// MySQL TIME type, represents a time of day.
+        /// </summary>
         TIME = 11,
+        
+        /// <summary>
+        /// MySQL DATETIME type, represents a combined date and time.
+        /// </summary>
         DATETIME = 12,
+        
+        /// <summary>
+        /// MySQL YEAR type, 1-byte representation of a year.
+        /// </summary>
         YEAR = 13,
+        
+        /// <summary>
+        /// MySQL NEWDATE type, new internal representation of DATE (rarely used externally).
+        /// </summary>
         NEWDATE = 14,
+        
+        /// <summary>
+        /// MySQL VARCHAR type, variable-length character string.
+        /// </summary>
         VARCHAR = 15,
+        
+        /// <summary>
+        /// MySQL BIT type, for storing bit values.
+        /// </summary>
         BIT = 16,
+        
+        /// <summary>
+        /// MySQL TIMESTAMP2 type, timestamp with fractional seconds, introduced in MySQL 5.6.4.
+        /// </summary>
         TIMESTAMP_V2 = 17,
+        
+        /// <summary>
+        /// MySQL DATETIME2 type, datetime with fractional seconds, introduced in MySQL 5.6.4.
+        /// </summary>
         DATETIME_V2 = 18,
+        
+        /// <summary>
+        /// MySQL TIME2 type, time with fractional seconds, introduced in MySQL 5.6.4.
+        /// </summary>
         TIME_V2 = 19,
+        
+        /// <summary>
+        /// MySQL JSON type for storing JSON documents, introduced in MySQL 5.7.
+        /// </summary>
         JSON = 245,
+        
+        /// <summary>
+        /// MySQL NEWDECIMAL type, new precision-based decimal implementation.
+        /// </summary>
         NEWDECIMAL = 246,
+        
+        /// <summary>
+        /// MySQL ENUM type, enumeration of string values.
+        /// </summary>
         ENUM = 247,
+        
+        /// <summary>
+        /// MySQL SET type, string object that can have zero or more values.
+        /// </summary>
         SET = 248,
+        
+        /// <summary>
+        /// MySQL TINY_BLOB type, small binary object.
+        /// </summary>
         TINY_BLOB = 249,
+        
+        /// <summary>
+        /// MySQL MEDIUM_BLOB type, medium-sized binary object.
+        /// </summary>
         MEDIUM_BLOB = 250,
+        
+        /// <summary>
+        /// MySQL LONG_BLOB type, large binary object.
+        /// </summary>
         LONG_BLOB = 251,
+        
+        /// <summary>
+        /// MySQL BLOB type, binary large object.
+        /// </summary>
         BLOB = 252,
+        
+        /// <summary>
+        /// MySQL VAR_STRING type, variable-length string (deprecated, VARCHAR is used instead).
+        /// </summary>
         VAR_STRING = 253,
+        
+        /// <summary>
+        /// MySQL STRING type, fixed-length string.
+        /// </summary>
         STRING = 254,
+        
+        /// <summary>
+        /// MySQL GEOMETRY type, for storing geometric data.
+        /// </summary>
         GEOMETRY = 255
     }
 }

src/SciSharp.MySQL.Replication/Events/FormatDescriptionEvent.cs

@@ -6,18 +6,37 @@
 namespace SciSharp.MySQL.Replication
 {
     /// <summary>
+    /// Represents a MySQL FORMAT_DESCRIPTION_EVENT that describes the format of the binary log.
+    /// This event appears at the beginning of each binary log file and provides information
+    /// about the server version and header lengths for each event type.
     /// https://dev.mysql.com/doc/internals/en/format-description-event.html
     /// </summary>
     public sealed class FormatDescriptionEvent : LogEvent
     {
+        /// <summary>
+        /// Gets or sets the binary log format version.
+        /// </summary>
         public short BinlogVersion { get; set; }
 
+        /// <summary>
+        /// Gets or sets the MySQL server version string.
+        /// </summary>
         public string ServerVersion { get; set; }
 
+        /// <summary>
+        /// Gets or sets the timestamp when the binary log was created.
+        /// </summary>
         public DateTime CreateTimestamp { get; set; }
 
+        /// <summary>
+        /// Gets or sets the length of the event header.
+        /// </summary>
         public byte EventHeaderLength { get; set; }
 
+        /// <summary>
+        /// Gets or sets the array of event type header lengths.
+        /// Each index corresponds to a LogEventType and contains the header length for that type.
+        /// </summary>
         public byte[] EventTypeHeaderLengths { get; set; }
 
         private string ReadServerVersion(ref SequenceReader<byte> reader, int len)
@@ -49,6 +68,11 @@ private string ReadServerVersion(ref SequenceReader<byte> reader, int len)
             }
         }
 
+        /// <summary>
+        /// Decodes the body of the event from the binary representation.
+        /// </summary>
+        /// <param name="reader">The sequence reader containing the binary data.</param>
+        /// <param name="context">The context for decoding.</param>
         protected internal override void DecodeBody(ref SequenceReader<byte> reader, object context)
         {
             reader.TryReadLittleEndian(out short version);
@@ -73,6 +97,10 @@ protected internal override void DecodeBody(ref SequenceReader<byte> reader, obj
             EventTypeHeaderLengths = eventTypeHeaderLens;            
         }
 
+        /// <summary>
+        /// Returns a string representation of the FormatDescriptionEvent.
+        /// </summary>
+        /// <returns>A string containing event information.</returns>
         public override string ToString()
         {
             return $"{EventType.ToString()}\r\nBinlogVersion: {BinlogVersion}\r\nServerVersion: {ServerVersion}";

src/SciSharp.MySQL.Replication/Events/QueryEvent.cs

@@ -5,20 +5,57 @@
 
 namespace SciSharp.MySQL.Replication
 {
+    /// <summary>
+    /// Represents a MySQL QUERY_EVENT that contains SQL statements executed on the server.
+    /// This event is generated for statements like CREATE, ALTER, INSERT, UPDATE, DELETE, etc.
+    /// that are not using row-based replication format.
+    /// </summary>
     public sealed class QueryEvent : LogEvent
     {
+        /// <summary>
+        /// Gets or sets the ID of the thread that executed the query.
+        /// </summary>
         public int SlaveProxyID { get; private set; }
+
+        /// <summary>
+        /// Gets or sets the time in seconds the query took to execute.
+        /// </summary>
         public DateTime ExecutionTime { get; private set; }
+
+        /// <summary>
+        /// Gets or sets the error code returned by the query execution.
+        /// A value of 0 indicates successful execution.
+        /// </summary>
         public short ErrorCode { get; private set; }
+
+        /// <summary>
+        /// Gets or sets the status variables block.
+        /// </summary>
         public string StatusVars { get; private set; }
+
+        /// <summary>
+        /// Gets or sets the database name that was active when the query was executed.
+        /// </summary>
         public string Schema { get; private set; }
+
+        /// <summary>
+        /// Gets or sets the SQL query text that was executed.
+        /// </summary>
         public String Query { get; private set; }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="QueryEvent"/> class.
+        /// </summary>
         public QueryEvent()
         {
             this.HasCRC = true;
         }
 
+        /// <summary>
+        /// Decodes the body of the event from the binary representation.
+        /// </summary>
+        /// <param name="reader">The sequence reader containing the binary data.</param>
+        /// <param name="context">The context for decoding.</param>
         protected internal override void DecodeBody(ref SequenceReader<byte> reader, object context)
         {
             reader.TryReadLittleEndian(out int slaveProxyID);
@@ -45,6 +82,10 @@ protected internal override void DecodeBody(ref SequenceReader<byte> reader, obj
             Query = reader.ReadString();
         }
 
+        /// <summary>
+        /// Returns a string representation of the QueryEvent.
+        /// </summary>
+        /// <returns>A string containing the event type, database name, and SQL query.</returns>
         public override string ToString()
         {
             return $"{EventType.ToString()}\r\nSlaveProxyID: {SlaveProxyID}\r\nExecutionTime: {ExecutionTime}\r\nErrorCode: {ErrorCode}\r\nStatusVars: {StatusVars}\r\nSchema: {Schema}\r\nQuery: {Query}";

src/SciSharp.MySQL.Replication/Events/RotateEvent.cs

@@ -6,14 +6,28 @@
 namespace SciSharp.MySQL.Replication
 {
     /// <summary>
+    /// Represents a MySQL ROTATE_EVENT that indicates a switch to a new binary log file.
+    /// This event is generated when the master server switches to a new binary log file,
+    /// either because the current file reached the max size or due to a manual rotation.
     /// https://dev.mysql.com/doc/internals/en/rotate-event.html
     /// </summary>
     public sealed class RotateEvent : LogEvent
     {
+        /// <summary>
+        /// Gets or sets the position in the new binary log file where the next event starts.
+        /// </summary>
         public long RotatePosition { get; set; }
 
+        /// <summary>
+        /// Gets or sets the name of the new binary log file.
+        /// </summary>
         public string NextBinlogFileName { get; set; }
 
+        /// <summary>
+        /// Decodes the body of the event from the binary representation.
+        /// </summary>
+        /// <param name="reader">The sequence reader containing the binary data.</param>
+        /// <param name="context">The context for decoding.</param>
         protected internal override void DecodeBody(ref SequenceReader<byte> reader, object context)
         {
             reader.TryReadLittleEndian(out long position);
@@ -25,6 +39,10 @@ protected internal override void DecodeBody(ref SequenceReader<byte> reader, obj
             reader.Advance(binglogFileNameSize);
         }
 
+        /// <summary>
+        /// Returns a string representation of the RotateEvent.
+        /// </summary>
+        /// <returns>A string containing the event type, new filename, and position information.</returns>
         public override string ToString()
         {
             return $"{EventType.ToString()}\r\nRotatePosition: {RotatePosition}\r\nNextBinlogFileName: {NextBinlogFileName}";

src/SciSharp.MySQL.Replication/Events/RowSet.cs

@@ -7,12 +7,36 @@
 
 namespace SciSharp.MySQL.Replication
 {
+    /// <summary>
+    /// Represents a set of rows affected by a row-based replication event.
+    /// Contains both the column names and the row data.
+    /// </summary>
     public sealed class RowSet
     {
+        /// <summary>
+        /// Gets or sets the list of column names.
+        /// </summary>
+        /// <remarks>
+        /// May be null if column names are not available in the binlog.
+        /// </remarks>
         public IReadOnlyList<string> ColumnNames { get; set; }
 
+        /// <summary>
+        /// Gets or sets the list of rows.
+        /// Each row is represented as an array of cell values.
+        /// </summary>
+        /// <remarks>
+        /// For UPDATE_ROWS_EVENT, the cell values are instances of CellValue containing both before and after values.
+        /// For WRITE_ROWS_EVENT and DELETE_ROWS_EVENT, the cell values are the direct column values.
+        /// </remarks>
         public IReadOnlyList<object[]> Rows { get; set; }
 
+        /// <summary>
+        /// Converts the rows into a readable format as a list of dictionaries.
+        /// Each dictionary represents a row with column names as keys and cell values as values.
+        /// </summary>
+        /// <returns>A list of dictionaries representing the rows.</returns>
+        /// <exception cref="Exception">Thrown when column names are not available.</exception>
         public IReadOnlyList<IDictionary<string, object>> ToReadableRows()
         {
             var columnNames = ColumnNames;