🚿 some docblocks and typos

src/Common/ECICharset.php

@@ -14,7 +14,7 @@ use chillerlan\QRCode\QRCodeException;
 use function array_key_exists;
 
 /**
- *
+ * ISO/IEC 18004:2000 - 8.4.1 Extended Channel Interpretation (ECI) Mode
  */
 final class ECICharset{
 

src/Common/GF256.php

@@ -99,7 +99,7 @@ final class GF256{
 	}
 
 	/**
-	 * @return int 2 to the power of a in GF(size)
+	 * @return int 2 to the power of $a in GF(size)
 	 */
 	public static function exp(int $a):int{
 
@@ -114,7 +114,7 @@ final class GF256{
 	}
 
 	/**
-	 * @return int base 2 log of a in GF(size)
+	 * @return int base 2 log of $a in GF(size)
 	 * @throws \chillerlan\QRCode\QRCodeException
 	 */
 	public static function log(int $a):int{

src/Common/GenericGFPoly.php

@@ -30,7 +30,7 @@ final class GenericGFPoly{
 
 	/**
 	 * @param array      $coefficients array coefficients as ints representing elements of GF(size), arranged
-	 *                                 from most significant (highest-power term) coefficient to least significant
+	 *                                 from most significant (highest-power term) coefficient to the least significant
 	 * @param int|null   $degree
 	 *
 	 * @throws \chillerlan\QRCode\QRCodeException if argument is null or empty, or if leading coefficient is 0 and this

src/Common/MaskPattern.php

@@ -25,6 +25,11 @@ use function abs, array_search, count, min;
  */
 final class MaskPattern{
 
+	/**
+	 * @see \chillerlan\QRCode\QROptionsTrait::$maskPattern
+	 *
+	 * @var int
+	 */
 	public const AUTO = -1;
 
 	public const PATTERN_000 = 0b000;
@@ -84,8 +89,8 @@ final class MaskPattern{
 	 * including areas used for finder patterns, timing patterns, etc. These areas should be unused
 	 * after the point they are unmasked anyway.
 	 *
-	 * Note that the diagram in section 6.8.1 is misleading since it indicates that i is column position
-	 * and j is row position. In fact, as the text says, i is row position and j is column position.
+	 * Note that the diagram in section 6.8.1 is misleading since it indicates that $i is column position
+	 * and $j is row position. In fact, as the text says, $i is row position and $j is column position.
 	 *
 	 * @see https://www.thonky.com/qr-code-tutorial/mask-patterns
 	 * @see https://github.com/zxing/zxing/blob/e9e2bd280bcaeabd59d0f955798384fe6c018a6c/core/src/main/java/com/google/zxing/qrcode/decoder/DataMask.java#L32-L117

src/Common/Version.php

@@ -13,10 +13,17 @@ namespace chillerlan\QRCode\Common;
 use chillerlan\QRCode\QRCodeException;
 
 /**
- *
+ * Version related tables and methods
  */
 final class Version{
 
+	/**
+	 * Enable version auto detection
+	 *
+	 * @see \chillerlan\QRCode\QROptionsTrait::$version
+	 *
+	 * @var int
+	 */
 	public const AUTO = -1;
 
 	/**
@@ -114,7 +121,7 @@ final class Version{
 	];
 
 	/**
-	 * ISO/IEC 18004:2000 Tables 13-22
+	 * ISO/IEC 18004:2000 Tables 13-22 - Error correction characteristics
 	 *
 	 * @see http://www.thonky.com/qr-code-tutorial/error-correction-table
 	 */
@@ -161,6 +168,9 @@ final class Version{
 		40 => [[30, [[19, 118], [ 6, 119]]], [28, [[18, 47], [31, 48]]], [30, [[34, 24], [34, 25]]], [30, [[20, 15], [61, 16]]]],
 	];
 
+	/**
+	 * ISO/IEC 18004:2000 Table 1 - Data capacity of all versions of QR Code
+	 */
 	private const TOTAL_CODEWORDS = [
 		1  => 26,
 		2  => 44,

src/Data/QRData.php

@@ -16,7 +16,7 @@ use chillerlan\Settings\SettingsContainerInterface;
 use function sprintf;
 
 /**
- * Processes the binary data and maps it on a matrix which is then being returned
+ * Processes the binary data and maps it on a QRMatrix which is then being returned
  */
 final class QRData{
 
@@ -99,7 +99,7 @@ final class QRData{
 	/**
 	 * Sets a BitBuffer object
 	 *
-	 * This can be used instead of setData(), however, the version auto detection is not available in this case.
+	 * This can be used instead of setData(), however, the version auto-detection is not available in this case.
 	 * The version needs match the length bits range for the data mode the data has been encoded with,
 	 * additionally the bit array needs to contain enough pad bits.
 	 *

src/Data/QRDataModeAbstract.php

@@ -13,11 +13,12 @@ namespace chillerlan\QRCode\Data;
 use chillerlan\QRCode\Common\Mode;
 
 /**
+ * abstract methods for the several data modes
  */
 abstract class QRDataModeAbstract implements QRDataModeInterface{
 
 	/**
-	 * the current data mode: Num, Alphanum, Kanji, Byte
+	 * the current data mode: Num, Alphanum, Kanji, Hanzi, Byte
 	 */
 	protected static int $datamode;
 
@@ -55,6 +56,13 @@ abstract class QRDataModeAbstract implements QRDataModeInterface{
 		return $this::$datamode;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
+	public static function convertEncoding(string $string):string{
+		return $string;
+	}
+
 	/**
 	 * shortcut
 	 */
@@ -62,13 +70,4 @@ abstract class QRDataModeAbstract implements QRDataModeInterface{
 		return Mode::getLengthBitsForVersion(static::$datamode, $versionNumber);
 	}
 
-	/**
-	 * encoding conversion helper
-	 *
-	 * @throws \chillerlan\QRCode\Data\QRCodeDataException
-	 */
-	public static function convertEncoding(string $string):string{
-		return $string;
-	}
-
 }

src/Data/QRDataModeInterface.php

@@ -27,6 +27,13 @@ interface QRDataModeInterface{
 	 */
 	public function getLengthInBits():int;
 
+	/**
+	 * encoding conversion helper
+	 *
+	 * @throws \chillerlan\QRCode\Data\QRCodeDataException
+	 */
+	public static function convertEncoding(string $string):string;
+
 	/**
 	 * checks if the given string qualifies for the encoder module
 	 */

src/Decoder/Binarizer.php

@@ -19,7 +19,7 @@ use function array_fill, count, max;
  * GlobalHistogramBinarizer, is fairly efficient for what it does. It is designed for
  * high frequency images of barcodes with black data on white backgrounds. For this application,
  * it does a much better job than a global blackpoint with severe shadows and gradients.
- * However it tends to produce artifacts on lower frequency images and is therefore not
+ * However, it tends to produce artifacts on lower frequency images and is therefore not
  * a good general purpose binarizer for uses outside ZXing.
  *
  * This class extends GlobalHistogramBinarizer, using the older histogram approach for 1D readers,
@@ -295,7 +295,7 @@ final class Binarizer{
 
 	/**
 	 * For each block in the image, calculate the average black point using a 5x5 grid
-	 * of the blocks around it. Also handles the corner cases (fractional blocks are computed based
+	 * of the surrounding blocks. Also handles the corner cases (fractional blocks are computed based
 	 * on the last pixels in the row/column which are also used in the previous block).
 	 */
 	private function calculateThresholdForBlock(int $subWidth, int $subHeight, int $width, int $height):BitMatrix{

src/Decoder/BitMatrix.php

@@ -17,7 +17,7 @@ use function array_fill, count;
 use const PHP_INT_MAX, PHP_INT_SIZE;
 
 /**
- *
+ * Extended QRMatrix to map read data from the Binarizer
  */
 final class BitMatrix extends QRMatrix{
 
@@ -78,8 +78,6 @@ final class BitMatrix extends QRMatrix{
 	 * This flag has effect only on the readFormatInformation() and the
 	 * readVersion() methods. Before proceeding with readCodewords() the
 	 * mirror() method should be called.
-	 *
-	 * @param bool $mirror Whether to read version and format information mirrored.
 	 */
 	public function setMirror(bool $mirror):self{
 		$this->version     = null;
@@ -110,10 +108,9 @@ final class BitMatrix extends QRMatrix{
 	/**
 	 * Reads the bits in the BitMatrix representing the finder pattern in the
 	 * correct order in order to reconstruct the codewords bytes contained within the
-	 * QR Code.
+	 * QR Code. Throws if the exact number of bytes expected is not read.
 	 *
-	 * @return array bytes encoded within the QR Code
-	 * @throws \chillerlan\QRCode\Decoder\QRCodeDecoderException if the exact number of bytes expected is not read
+	 * @throws \chillerlan\QRCode\Decoder\QRCodeDecoderException
 	 */
 	public function readCodewords():array{
 
@@ -172,14 +169,15 @@ final class BitMatrix extends QRMatrix{
 			throw new QRCodeDecoderException('result count differs from total codewords for version');
 		}
 
+		// bytes encoded within the QR Code
 		return $result;
 	}
 
 	/**
 	 * Reads format information from one of its two locations within the QR Code.
+	 * Throws if both format information locations cannot be parsed as the valid encoding of format information.
 	 *
-	 * @throws \chillerlan\QRCode\Decoder\QRCodeDecoderException if both format information locations cannot be parsed as
-	 *                                                           the valid encoding of format information
+	 * @throws \chillerlan\QRCode\Decoder\QRCodeDecoderException
 	 */
 	private function readFormatInformation():self{
 
@@ -194,11 +192,11 @@ final class BitMatrix extends QRMatrix{
 			$formatInfoBits1 = $this->copyVersionBit($i, 8, $formatInfoBits1);
 		}
 
-		// .. and skip a bit in the timing pattern ...
+		// ... and skip a bit in the timing pattern ...
 		$formatInfoBits1 = $this->copyVersionBit(7, 8, $formatInfoBits1);
 		$formatInfoBits1 = $this->copyVersionBit(8, 8, $formatInfoBits1);
 		$formatInfoBits1 = $this->copyVersionBit(8, 7, $formatInfoBits1);
-		// .. and skip a bit in the timing pattern ...
+		// ... and skip a bit in the timing pattern ...
 		for($j = 5; $j >= 0; $j--){
 			$formatInfoBits1 = $this->copyVersionBit(8, $j, $formatInfoBits1);
 		}
@@ -252,17 +250,13 @@ final class BitMatrix extends QRMatrix{
 	}
 
 	/**
-	 * @param int $maskedFormatInfo1 format info indicator, with mask still applied
-	 * @param int $maskedFormatInfo2 second copy of same info; both are checked at the same time
-	 *                               to establish best match
-	 *
-	 * @return int|null information about the format it specifies, or null if doesn't seem to match any known pattern
+	 * Returns information about the format it specifies, or null if it doesn't seem to match any known pattern
 	 */
 	private function doDecodeFormatInformation(int $maskedFormatInfo1, int $maskedFormatInfo2):?int{
-		// Find the int in FORMAT_INFO_DECODE_LOOKUP with fewest bits differing
 		$bestDifference = PHP_INT_MAX;
 		$bestFormatInfo = 0;
 
+		// Find the int in FORMAT_INFO_DECODE_LOOKUP with the fewest bits differing
 		foreach($this::DECODE_LOOKUP as $maskedBits => $dataBits){
 
 			if($maskedFormatInfo1 === $dataBits || $maskedFormatInfo2 === $dataBits){
@@ -297,9 +291,9 @@ final class BitMatrix extends QRMatrix{
 
 	/**
 	 * Reads version information from one of its two locations within the QR Code.
+	 * Throws if both version information locations cannot be parsed as the valid encoding of version information.
 	 *
-	 * @throws \chillerlan\QRCode\Decoder\QRCodeDecoderException if both version information locations cannot be parsed as
-	 *                                                           the valid encoding of version information
+	 * @throws \chillerlan\QRCode\Decoder\QRCodeDecoderException
 	 * @noinspection DuplicatedCode
 	 */
 	private function readVersion():self{
@@ -352,7 +346,7 @@ final class BitMatrix extends QRMatrix{
 	}
 
 	/**
-	 *
+	 * Decodes the version information from the given bit sequence, returns null if no valid match is found.
 	 */
 	private function decodeVersionInformation(int $versionBits):?Version{
 		$bestDifference = PHP_INT_MAX;
@@ -405,7 +399,7 @@ final class BitMatrix extends QRMatrix{
 	private function numBitsDiffering(int $a, int $b):int{
 		// a now has a 1 bit exactly where its bit differs with b's
 		$a ^= $b;
-		// Offset i holds the number of 1 bits in the binary representation of i
+		// Offset $i holds the number of 1-bits in the binary representation of $i
 		$BITS_SET_IN_HALF_BYTE = [0, 1, 1, 2, 1, 2, 2, 3, 1, 2, 2, 3, 2, 3, 3, 4];
 		// Count bits set quickly with a series of lookups:
 		$count = 0;

src/Decoder/Decoder.php

@@ -15,7 +15,7 @@ use chillerlan\QRCode\Common\{BitBuffer, EccLevel, MaskPattern, Mode, ReedSolomo
 use chillerlan\QRCode\Data\{AlphaNum, Byte, ECI, Hanzi, Kanji, Number};
 use chillerlan\QRCode\Detector\Detector;
 use Throwable;
-use function array_fill, chr, count, mb_convert_encoding, mb_detect_encoding, mb_internal_encoding, str_replace;
+use function chr, mb_convert_encoding, mb_detect_encoding, mb_internal_encoding, str_replace;
 
 /**
  * The main class which implements QR Code decoding -- as opposed to locating and extracting

src/Decoder/DecoderResult.php

@@ -17,10 +17,10 @@ use function property_exists;
 
 /**
  * Encapsulates the result of decoding a matrix of bits. This typically
- * applies to 2D barcode formats. For now it contains the raw bytes obtained,
+ * applies to 2D barcode formats. For now, it contains the raw bytes obtained
  * as well as a String interpretation of those bytes, if applicable.
  *
- * @property int[]                                 $rawBytes
+ * @property \chillerlan\QRCode\Common\BitBuffer   $rawBytes
  * @property string                                $data
  * @property \chillerlan\QRCode\Common\Version     $version
  * @property \chillerlan\QRCode\Common\EccLevel    $eccLevel
@@ -31,10 +31,10 @@ use function property_exists;
 final class DecoderResult{
 
 	private BitBuffer   $rawBytes;
-	private string      $data;
 	private Version     $version;
 	private EccLevel    $eccLevel;
 	private MaskPattern $maskPattern;
+	private string      $data = '';
 	private int         $structuredAppendParity = -1;
 	private int         $structuredAppendSequence = -1;
 

src/Decoder/LuminanceSourceInterface.php

@@ -18,8 +18,8 @@ interface LuminanceSourceInterface{
 	 * Fetches luminance data for the underlying bitmap. Values should be fetched using:
 	 * `int luminance = array[y * width + x] & 0xff`
 	 *
-	 * @return array A row-major 2D array of luminance values. Do not use result.length as it may be
-	 *         larger than width * height bytes on some platforms. Do not modify the contents
+	 * @return array A row-major 2D array of luminance values. Do not use result $length as it may be
+	 *         larger than $width * $height bytes on some platforms. Do not modify the contents
 	 *         of the result.
 	 */
 	public function getLuminances():array;

src/Detector/AlignmentPatternFinder.php

@@ -42,9 +42,9 @@ final class AlignmentPatternFinder{
 	 * @param float                                $moduleSize estimated module size so far
 	 */
 	public function __construct(BitMatrix $matrix, float $moduleSize){
-		$this->matrix     = $matrix;
-		$this->moduleSize = $moduleSize;
-		$this->possibleCenters      = [];
+		$this->matrix          = $matrix;
+		$this->moduleSize      = $moduleSize;
+		$this->possibleCenters = [];
 	}
 
 	/**
@@ -164,7 +164,7 @@ final class AlignmentPatternFinder{
 
 	/**
 	 * This is called when a horizontal scan finds a possible alignment pattern. It will
-	 * cross check with a vertical scan, and if successful, will see if this pattern had been
+	 * cross-check with a vertical scan, and if successful, will see if this pattern had been
 	 * found on a previous horizontal scan. If so, we consider it confirmed and conclude we have
 	 * found the alignment pattern.
 	 *
@@ -207,7 +207,7 @@ final class AlignmentPatternFinder{
 	 * @return float
 	 */
 	private function centerFromEnd(array $stateCount, int $end):float{
-		return (float)(($end - $stateCount[2]) - $stateCount[1] / 2.0);
+		return (float)(($end - $stateCount[2]) - $stateCount[1] / 2);
 	}
 
 	/**

src/Detector/FinderPatternFinder.php

@@ -188,7 +188,7 @@ final class FinderPatternFinder{
 	 * @param int[] $stateCount
 	 */
 	private function centerFromEnd(array $stateCount, int $end):float{
-		return (float)(($end - $stateCount[4] - $stateCount[3]) - $stateCount[2] / 2.0);
+		return (float)(($end - $stateCount[4] - $stateCount[3]) - $stateCount[2] / 2);
 	}
 
 	/**
@@ -246,8 +246,8 @@ final class FinderPatternFinder{
 	 * "cross-cross-cross-checks" by scanning down diagonally through the center of the possible
 	 * finder pattern to see if the same proportion is detected.
 	 *
-	 * @param $centerI ;  row where a finder pattern was detected
-	 * @param $centerJ ; center of the section that appears to cross a finder pattern
+	 * @param int $centerI row where a finder pattern was detected
+	 * @param int $centerJ center of the section that appears to cross a finder pattern
 	 *
 	 * @return bool true if proportions are withing expected limits
 	 */
@@ -321,9 +321,9 @@ final class FinderPatternFinder{
 	 * "cross-checks" by scanning down vertically through the center of the possible
 	 * finder pattern to see if the same proportion is detected.
 	 *
-	 * @param int $startI   ;  row where a finder pattern was detected
-	 * @param int $centerJ  ; center of the section that appears to cross a finder pattern
-	 * @param int $maxCount ; maximum reasonable number of modules that should be
+	 * @param int $startI   row where a finder pattern was detected
+	 * @param int $centerJ  center of the section that appears to cross a finder pattern
+	 * @param int $maxCount maximum reasonable number of modules that should be
 	 *                      observed in any reading state, based on the results of the horizontal scan
 	 * @param int $originalStateCountTotal
 	 *
@@ -393,7 +393,7 @@ final class FinderPatternFinder{
 			return null;
 		}
 
-		// If we found a finder-pattern-like section, but its size is more than 40% different than
+		// If we found a finder-pattern-like section, but its size is more than 40% different from
 		// the original, assume it's a false positive
 		$stateCountTotal = $stateCount[0] + $stateCount[1] + $stateCount[2] + $stateCount[3] + $stateCount[4];
 
@@ -411,7 +411,7 @@ final class FinderPatternFinder{
 	/**
 	 * Like #crossCheckVertical(int, int, int, int), and in fact is basically identical,
 	 * except it reads horizontally instead of vertically. This is used to cross-cross
-	 * check a vertical cross check and locate the real center of the alignment pattern.
+	 * check a vertical cross-check and locate the real center of the alignment pattern.
 	 * @noinspection DuplicatedCode
 	 */
 	private function crossCheckHorizontal(int $startJ, int $centerI, int $maxCount, int $originalStateCountTotal):?float{
@@ -474,7 +474,7 @@ final class FinderPatternFinder{
 			return null;
 		}
 
-		// If we found a finder-pattern-like section, but its size is significantly different than
+		// If we found a finder-pattern-like section, but its size is significantly different from
 		// the original, assume it's a false positive
 		$stateCountTotal = $stateCount[0] + $stateCount[1] + $stateCount[2] + $stateCount[3] + $stateCount[4];
 
@@ -491,7 +491,7 @@ final class FinderPatternFinder{
 
 	/**
 	 * This is called when a horizontal scan finds a possible alignment pattern. It will
-	 * cross check with a vertical scan, and if successful, will, ah, cross-cross-check
+	 * cross-check with a vertical scan, and if successful, will, ah, cross-cross-check
 	 * with another horizontal scan. This is needed primarily to locate the real horizontal
 	 * center of the pattern in cases of extreme skew.
 	 * And then we cross-cross-cross check with another diagonal scan.

src/Output/QREps.php

@@ -122,7 +122,7 @@ class QREps extends QROutputAbstract{
 		$outputX = $x * $this->scale;
 		// Actual size - one block = Topmost y pos.
 		$top     = $this->length - $this->scale;
-		// Apparently y-axis is inverted (y0 is at bottom and not top) in EPS so we have to switch the y-axis here
+		// Apparently y-axis is inverted (y0 is at bottom and not top) in EPS, so we have to switch the y-axis here
 		$outputY = $top - ($y * $this->scale);
 
 		return sprintf('%d %d %d %d F', $outputX, $outputY, $this->scale, $this->scale);

src/QRCode.php

@@ -185,7 +185,7 @@ class QRCode{
 	public function __construct(SettingsContainerInterface $options = null){
 		$this->options = $options ?? new QROptions;
 
-		// i hate this less
+		// I hate this less
 		if($this->options->readerUseImagickIfAvailable){
 			$this->luminanceSourceFQN = IMagickLuminanceSource::class;
 		}
@@ -432,7 +432,7 @@ class QRCode{
 	 *
 	 * The given string will be encoded from mb_internal_encoding() to the given ECI character set
 	 *
-	 * i hate this somehow but i'll leave it for now
+	 * I hate this somehow, but I'll leave it for now
 	 *
 	 * @throws \chillerlan\QRCode\QRCodeException
 	 */