Merge pull request #517 from Shane32/comments

Add code comments to QR code generation

Author: codebude

QRCoder/QRCodeGenerator.AlignmentPattern.cs

@@ -4,9 +4,21 @@ namespace QRCoder
 {
     public partial class QRCodeGenerator
     {
+        /// <summary>
+        /// Represents the alignment pattern used in QR codes, which helps ensure the code remains readable even if it is somewhat distorted.
+        /// Each QR code version has its own specific alignment pattern locations which this struct encapsulates.
+        /// </summary>
         private struct AlignmentPattern
         {
+            /// <summary>
+            /// The version of the QR code. Higher versions have more complex and numerous alignment patterns.
+            /// </summary>
             public int Version;
+
+            /// <summary>
+            /// A list of points where alignment patterns are located within the QR code matrix.
+            /// Each point represents the center of an alignment pattern.
+            /// </summary>
             public List<Point> PatternPositions;
         }
     }

QRCoder/QRCodeGenerator.CodewordBlock.cs

@@ -2,15 +2,31 @@
 {
     public partial class QRCodeGenerator
     {
+        /// <summary>
+        /// Represents a block of codewords in a QR code. QR codes are divided into several blocks for error correction purposes.
+        /// Each block contains a series of data codewords followed by error correction codewords.
+        /// </summary>
         private struct CodewordBlock
         {
+            /// <summary>
+            /// Initializes a new instance of the CodewordBlock struct with specified arrays of code words and error correction (ECC) words.
+            /// </summary>
+            /// <param name="codeWords">The array of data codewords for this block. Data codewords carry the actual information.</param>
+            /// <param name="eccWords">The array of error correction codewords for this block. These codewords help recover the data if the QR code is damaged.</param>
             public CodewordBlock(byte[] codeWords, byte[] eccWords)
             {
                 this.CodeWords = codeWords;
                 this.ECCWords = eccWords;
             }
 
+            /// <summary>
+            /// Gets the data codewords associated with this block. 
+            /// </summary>
             public byte[] CodeWords { get; }
+
+            /// <summary>
+            /// Gets the error correction codewords associated with this block.
+            /// </summary>
             public byte[] ECCWords { get; }
         }
     }

QRCoder/QRCodeGenerator.ECCInfo.cs

@@ -2,8 +2,22 @@
 {
     public partial class QRCodeGenerator
     {
+        /// <summary>
+        /// Represents the error correction coding (ECC) information for a specific version and error correction level of a QR code.
+        /// </summary>
         private struct ECCInfo
         {
+            /// <summary>
+            /// Initializes a new instance of the ECCInfo struct with specified properties.
+            /// </summary>
+            /// <param name="version">The version number of the QR code.</param>
+            /// <param name="errorCorrectionLevel">The error correction level used in the QR code.</param>
+            /// <param name="totalDataCodewords">The total number of data codewords for this version and error correction level.</param>
+            /// <param name="eccPerBlock">The number of error correction codewords per block.</param>
+            /// <param name="blocksInGroup1">The number of blocks in group 1.</param>
+            /// <param name="codewordsInGroup1">The number of codewords in each block of group 1.</param>
+            /// <param name="blocksInGroup2">The number of blocks in group 2, if any.</param>
+            /// <param name="codewordsInGroup2">The number of codewords in each block of group 2, if any.</param>
             public ECCInfo(int version, ECCLevel errorCorrectionLevel, int totalDataCodewords, int eccPerBlock, int blocksInGroup1,
                 int codewordsInGroup1, int blocksInGroup2, int codewordsInGroup2)
             {
@@ -16,13 +30,45 @@ public ECCInfo(int version, ECCLevel errorCorrectionLevel, int totalDataCodeword
                 this.BlocksInGroup2 = blocksInGroup2;
                 this.CodewordsInGroup2 = codewordsInGroup2;
             }
+
+            /// <summary>
+            /// Gets the version number of the QR code.
+            /// </summary>
             public int Version { get; }
+
+            /// <summary>
+            /// Gets the error correction level of the QR code.
+            /// </summary>
             public ECCLevel ErrorCorrectionLevel { get; }
+
+            /// <summary>
+            /// Gets the total number of data codewords for this version and error correction level.
+            /// </summary>
             public int TotalDataCodewords { get; }
+
+            /// <summary>
+            /// Gets the number of error correction codewords per block.
+            /// </summary>
             public int ECCPerBlock { get; }
+
+            /// <summary>
+            /// Gets the number of blocks in group 1.
+            /// </summary>
             public int BlocksInGroup1 { get; }
+
+            /// <summary>
+            /// Gets the number of codewords in each block of group 1.
+            /// </summary>
             public int CodewordsInGroup1 { get; }
+
+            /// <summary>
+            /// Gets the number of blocks in group 2, if any.
+            /// </summary>
             public int BlocksInGroup2 { get; }
+
+            /// <summary>
+            /// Gets the number of codewords in each block of group 2, if any.
+            /// </summary>
             public int CodewordsInGroup2 { get; }
         }
     }

QRCoder/QRCodeGenerator.ECCLevel.cs

@@ -3,24 +3,32 @@
     public partial class QRCodeGenerator
     {
         /// <summary>
-        /// Error correction level. These define the tolerance levels for how much of the code can be lost before the code cannot be recovered.
+        /// Defines the levels of error correction available in QR codes.
+        /// Each level specifies the proportion of data that can be recovered if the QR code is partially obscured or damaged.
         /// </summary>
         public enum ECCLevel
         {
             /// <summary>
-            /// 7% may be lost before recovery is not possible
+            /// Level L: Low error correction (approximately 7% of data can be recovered).
+            /// This level allows the highest data density.
             /// </summary>
             L,
+
             /// <summary>
-            /// 15% may be lost before recovery is not possible
+            /// Level M: Medium error correction (approximately 15% of data can be recovered).
+            /// Offers a balance between data capacity and error recovery.
             /// </summary>
             M,
+
             /// <summary>
-            /// 25% may be lost before recovery is not possible
+            /// Level Q: Quartile error correction (approximately 25% of data can be recovered).
+            /// More robust error correction at the cost of reduced data capacity.
             /// </summary>
             Q,
+
             /// <summary>
-            /// 30% may be lost before recovery is not possible
+            /// Level H: High error correction (approximately 30% of data can be recovered).
+            /// Provides the highest level of error recovery, ideal for environments with high risk of data loss.
             /// </summary>
             H
         }

QRCoder/QRCodeGenerator.EciMode.cs

@@ -2,11 +2,34 @@
 {
     public partial class QRCodeGenerator
     {
+        /// <summary>
+        /// Enumerates the Extended Channel Interpretation (ECI) modes used in QR codes to handle different character encoding standards.
+        /// ECI mode allows QR codes to efficiently encode data using character sets other than the default ISO-8859-1.
+        /// </summary>
         public enum EciMode
         {
+            /// <summary>
+            /// Default encoding mode (typically ISO-8859-1). Used when no ECI mode is explicitly specified.
+            /// This mode is assumed in basic QR codes where no extended character sets are needed.
+            /// </summary>
             Default = 0,
+
+            /// <summary>
+            /// Specifies the use of the ISO-8859-1 character set, covering most Western European languages.
+            /// This mode explicitly sets the encoding to ISO-8859-1, which includes characters used in languages such as English, French, German, and Spanish.
+            /// </summary>
             Iso8859_1 = 3,
+
+            /// <summary>
+            /// Specifies the use of the ISO-8859-2 character set, which is primarily used for Central and Eastern European languages.
+            /// This includes characters used in languages such as Polish, Czech, Slovak, Hungarian, and Romanian.
+            /// </summary>
             Iso8859_2 = 4,
+
+            /// <summary>
+            /// Specifies the use of UTF-8 encoding.
+            /// UTF-8 can encode any Unicode character and is useful for QR codes that need to support multi-language content.
+            /// </summary>
             Utf8 = 26
         }
     }

QRCoder/QRCodeGenerator.EncodingMode.cs

@@ -1,13 +1,42 @@
-namespace QRCoder
+using System;
+
+namespace QRCoder
 {
     public partial class QRCodeGenerator
     {
+        /// <summary>
+        /// Specifies the encoding modes for the characters in a QR code.
+        /// </summary>
         private enum EncodingMode
         {
+            /// <summary>
+            /// Numeric encoding mode, which is used to encode numeric data (digits 0-9).
+            /// Three characters are encoded into 10 bits.
+            /// </summary>
             Numeric = 1,
+
+            /// <summary>
+            /// Alphanumeric encoding mode, which is used to encode alphanumeric characters (0-9, A-Z, space, and some punctuation).
+            /// Two characters are encoded into 11 bits.
+            /// </summary>
             Alphanumeric = 2,
+
+            /// <summary>
+            /// Byte encoding mode, primarily using the ISO-8859-1 character set. Each character is encoded into 8 bits.
+            /// When combined with ECI, it can be adapted to use other character sets.
+            /// </summary>
             Byte = 4,
+
+            /// <summary>
+            /// Kanji encoding mode, which is used to encode characters from the Shift JIS character set, primarily for Japanese Kanji and Kana characters.
+            /// One character is encoded into 13 bits. This mode is not currently supported by QRCoder.
+            /// </summary>
             Kanji = 8,
+
+            /// <summary>
+            /// Extended Channel Interpretation (ECI) mode, which specifies a character set via an 8-bit number followed by one of the other encoding modes.
+            /// This allows adapting the byte encoding to accommodate various global text encodings.
+            /// </summary>
             ECI = 7
         }
     }