From b7a0be19c57aa0e05d2adbbdd087c1f1b810c49d Mon Sep 17 00:00:00 2001
From: Chlod Alejandro <chlod@chlod.net>
Date: Sat, 11 May 2024 14:47:56 +0800
Subject: [PATCH] Explain capitalization process

Add comments into the code for converting page cases
from lowercase (first letter) to uppercase.

Change-Id: I3ae3602d826e232adc1ce6063ac6b50eac01d5bc
---
 includes/SpecialNuke.php | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/includes/SpecialNuke.php b/includes/SpecialNuke.php
index f997c5ff..2bf9a10c 100644
--- a/includes/SpecialNuke.php
+++ b/includes/SpecialNuke.php
@@ -140,7 +140,7 @@ class SpecialNuke extends SpecialPage {
 	 *
 	 * @param string $userName
 	 */
-	protected function promptForm( $userName = '' ): void {
+	protected function promptForm( string $userName = '' ): void {
 		$out = $this->getOutput();
 
 		$out->addWikiMsg( 'nuke-tools' );
@@ -369,29 +369,44 @@ class SpecialNuke extends SpecialPage {
 		$pattern = $this->getRequest()->getText( 'pattern' );
 		if ( $pattern !== null && trim( $pattern ) !== '' ) {
 			$addedWhere = false;
+
 			$pattern = trim( $pattern );
 			$pattern = preg_replace( '/ +/', '`_', $pattern );
 			$pattern = preg_replace( '/\\\\([%_])/', '`$1', $pattern );
+
 			if ( $namespace !== null ) {
+				// Custom namespace requested
+				// If that namespace capitalizes titles, capitalize the first character
+				// to match the DB title.
 				$pattern = $this->namespaceInfo->isCapitalized( $namespace ) ?
 					$this->contentLanguage->ucfirst( $pattern ) : $pattern;
 			} else {
+				// All namespaces requested
+
 				$overriddenNamespaces = [];
 				$capitalLinks = $this->getConfig()->get( 'CapitalLinks' );
 				$capitalLinkOverrides = $this->getConfig()->get( 'CapitalLinkOverrides' );
+				// If there are any capital-overridden namespaces, keep track of them. "overridden"
+				// here means the namespace-specific value is not equal to $wgCapitalLinks.
 				foreach ( $capitalLinkOverrides as $k => $v ) {
 					if ( $v !== $capitalLinks ) {
 						$overriddenNamespaces[] = $k;
 					}
 				}
+
 				if ( count( $overriddenNamespaces ) ) {
+					// If there are overridden namespaces, they have to be converted
+					// on a case-by-case basis.
+
 					$validNamespaces = $this->namespaceInfo->getValidNamespaces();
 					$nonOverriddenNamespaces = [];
 					foreach ( $validNamespaces as $ns ) {
 						if ( !in_array( $ns, $overriddenNamespaces ) ) {
+							// Put all namespaces that aren't overridden in $nonOverriddenNamespaces
 							$nonOverriddenNamespaces[] = $ns;
 						}
 					}
+
 					$patternSpecific = $this->namespaceInfo->isCapitalized( $overriddenNamespaces[0] ) ?
 						$this->contentLanguage->ucfirst( $pattern ) : $pattern;
 					$orConditions = [
@@ -400,6 +415,7 @@ class SpecialNuke extends SpecialPage {
 								new LikeMatch( $patternSpecific )
 							)
 						)->and(
+							// IN condition
 							'page_namespace', '=', $overriddenNamespaces
 						)
 					];
@@ -411,12 +427,16 @@ class SpecialNuke extends SpecialPage {
 								new LikeMatch( $patternStandard )
 							)
 						)->and(
+							// IN condition, with the non-overridden namespaces.
+							// If the default is case-sensitive namespaces, $pattern's first
+							// character is turned lowercase. Otherwise, it is turned uppercase.
 							'page_namespace', '=', $nonOverriddenNamespaces
 						);
 					}
 					$queryBuilder->andWhere( new OrExpressionGroup( ...$orConditions ) );
 					$addedWhere = true;
 				} else {
+					// No overridden namespaces; just convert all titles.
 					$pattern = $this->namespaceInfo->isCapitalized( NS_MAIN ) ?
 						$this->contentLanguage->ucfirst( $pattern ) : $pattern;
 				}