From 2a38174f72055aeba84ed8e2f9e8f90f12fdd949 Mon Sep 17 00:00:00 2001
From: Thiemo Kreuz <thiemo.kreuz@wikimedia.de>
Date: Tue, 5 Jun 2018 13:50:26 +0200
Subject: [PATCH] ExternalUserNames: Update partly incomplete documentation

Bug: T192376
Change-Id: Iae9c537a82046e26cbe5d1703bfe428a38a91f10
---
 includes/user/ExternalUserNames.php | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/includes/user/ExternalUserNames.php b/includes/user/ExternalUserNames.php
index f953b144d8..66674dca10 100644
--- a/includes/user/ExternalUserNames.php
+++ b/includes/user/ExternalUserNames.php
@@ -27,8 +27,20 @@ use MediaWiki\MediaWikiServices;
  * @since 1.31
  */
 class ExternalUserNames {
+
+	/**
+	 * @var string
+	 */
 	private $usernamePrefix = 'imported';
+
+	/**
+	 * @var bool
+	 */
 	private $assignKnownUsers = false;
+
+	/**
+	 * @var bool[]
+	 */
 	private $triedCreations = [];
 
 	/**
@@ -69,8 +81,16 @@ class ExternalUserNames {
 	/**
 	 * Add an interwiki prefix to the username, if appropriate
 	 *
-	 * @param string $name Name being imported
-	 * @return string Name, possibly with the prefix prepended.
+	 * This method does have a side-effect on SUL (single user login) wikis: Calling this calls the
+	 * ImportHandleUnknownUser hook from the CentralAuth extension, which assigns a local ID to the
+	 * global user name, if possible. No prefix is applied if this is successful.
+	 *
+	 * @see https://meta.wikimedia.org/wiki/Help:Unified_login
+	 * @see https://www.mediawiki.org/wiki/Manual:Hooks/ImportHandleUnknownUser
+	 *
+	 * @param string $name
+	 * @return string Either the unchanged username if it's a known local user (or not a valid
+	 *  username), otherwise the name with the prefix prepended.
 	 */
 	public function applyPrefix( $name ) {
 		if ( !User::isUsableName( $name ) ) {
@@ -99,8 +119,8 @@ class ExternalUserNames {
 	/**
 	 * Add an interwiki prefix to the username regardless of circumstances
 	 *
-	 * @param string $name Name being imported
-	 * @return string Name
+	 * @param string $name
+	 * @return string Prefixed username, using ">" as separator
 	 */
 	public function addPrefix( $name ) {
 		return substr( $this->usernamePrefix . '>' . $name, 0, 255 );
-- 
2.20.1