Improve normalizePageName documentation

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

diff --git a/includes/site/MediaWikiPageNameNormalizer.php b/includes/site/MediaWikiPageNameNormalizer.php
index 3e073f0..8a12c4f 100644 (file)
--- 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 0ff7e8b..e1e7ce6 100644 (file)
--- 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 55aad77..f5e3f22 100644 (file)
--- 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
         *