From c1afba8ccfe12bd69d13937ee87fce0d2a80fd03 Mon Sep 17 00:00:00 2001
From: Lucas Werkmeister <lucas.werkmeister@wikimedia.de>
Date: Wed, 11 Apr 2018 15:48:16 +0200
Subject: [PATCH] Improve normalizePageName documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

Even though it wasn’t documented in the interface,
MediaWikiPageNameNormalizer::normalizePageName returns false for pages
that do not exist on the remote site. Too many users already depend on
this feature to remove it, so at least document it properly.

Change-Id: Ic2ba86b81bba86b868a6697aa57fdd46432c0d7d
---
 includes/site/MediaWikiPageNameNormalizer.php | 5 ++++-
 includes/site/MediaWikiSite.php               | 5 ++++-
 includes/site/Site.php                        | 6 ++++--
 3 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/includes/site/MediaWikiPageNameNormalizer.php b/includes/site/MediaWikiPageNameNormalizer.php
index 3e073f0882..8a12c4f7ce 100644
--- a/includes/site/MediaWikiPageNameNormalizer.php
+++ b/includes/site/MediaWikiPageNameNormalizer.php
@@ -54,6 +54,7 @@ class MediaWikiPageNameNormalizer {
 	 * Returns the normalized form of the given page title, using the
 	 * normalization rules of the given site. If the given title is a redirect,
 	 * the redirect will be resolved and the redirect target is returned.
+	 * Only titles of existing pages will be returned.
 	 *
 	 * @note This actually makes an API request to the remote site, so beware
 	 *   that this function is slow and depends on an external service.
@@ -65,7 +66,9 @@ class MediaWikiPageNameNormalizer {
 	 * @param string $pageName
 	 * @param string $apiUrl
 	 *
-	 * @return string|false
+	 * @return string|false The normalized form of the title,
+	 * or false to indicate an invalid title, a missing page,
+	 * or some other kind of error.
 	 * @throws \MWException
 	 */
 	public function normalizePageName( $pageName, $apiUrl ) {
diff --git a/includes/site/MediaWikiSite.php b/includes/site/MediaWikiSite.php
index 0ff7e8bad4..e1e7ce69cf 100644
--- a/includes/site/MediaWikiSite.php
+++ b/includes/site/MediaWikiSite.php
@@ -65,6 +65,7 @@ class MediaWikiSite extends Site {
 	 * Returns the normalized form of the given page title, using the
 	 * normalization rules of the given site. If the given title is a redirect,
 	 * the redirect will be resolved and the redirect target is returned.
+	 * Only titles of existing pages will be returned.
 	 *
 	 * @note This actually makes an API request to the remote site, so beware
 	 *   that this function is slow and depends on an external service.
@@ -79,7 +80,9 @@ class MediaWikiSite extends Site {
 	 *
 	 * @param string $pageName
 	 *
-	 * @return string|false
+	 * @return string|false The normalized form of the title,
+	 * or false to indicate an invalid title, a missing page,
+	 * or some other kind of error.
 	 * @throws MWException
 	 */
 	public function normalizePageName( $pageName ) {
diff --git a/includes/site/Site.php b/includes/site/Site.php
index 55aad77831..f5e3f22ee6 100644
--- a/includes/site/Site.php
+++ b/includes/site/Site.php
@@ -382,8 +382,10 @@ class Site implements Serializable {
 	}
 
 	/**
-	 * Returns $pageName without changes.
-	 * Subclasses may override this to apply some kind of normalization.
+	 * Attempt to normalize the page name in some fashion.
+	 * May return false to indicate various kinds of failure.
+	 *
+	 * This implementation returns $pageName without changes.
 	 *
 	 * @see Site::normalizePageName
 	 *
-- 
2.20.1