From 0300b5af4934728672eda3186fa89758b77235cc Mon Sep 17 00:00:00 2001
From: =?utf8?q?Bartosz=20Dziewo=C5=84ski?= <matma.rex@gmail.com>
Date: Wed, 13 Aug 2014 13:55:55 +0200
Subject: [PATCH] SkinFactory: Improve documentation and comments

* Document parameters to register()
* Document what the "human-readable name" does
* Document the distinction between autodiscovery and $wgValidSkinNames
  skins

Change-Id: Iee5bd18b3e68f3e48ccd28e386109e60fee31085
---
 includes/skins/SkinFactory.php | 30 ++++++++++++++++++------------
 1 file changed, 18 insertions(+), 12 deletions(-)

diff --git a/includes/skins/SkinFactory.php b/includes/skins/SkinFactory.php
index 52eaddd532..d5f25463e6 100644
--- a/includes/skins/SkinFactory.php
+++ b/includes/skins/SkinFactory.php
@@ -34,14 +34,16 @@ class SkinFactory {
 	 */
 	private $factoryFunctions = array();
 	/**
-	 * Map of name => human readable name
+	 * Map of name => fallback human-readable name, used when the 'skinname-<skin>' message is not
+	 * available
+	 *
 	 * @var array
 	 */
 	private $displayNames = array();
-
 	/**
-	 * Map of name => class name without "Skin" prefix
-	 * for legacy skins using the autoloader
+	 * Map of name => class name without "Skin" prefix, for legacy skins using the autodiscovery
+	 * mechanism
+	 *
 	 * @var array
 	 */
 	private $legacySkins = array();
@@ -60,11 +62,16 @@ class SkinFactory {
 	}
 
 	/**
-	 * Register a new Skin factory function
-	 * Will override if it's already registered
-	 * @param string $name
-	 * @param string $displayName
-	 * @param callable $callback That takes the skin name as an argument
+	 * Register a new Skin factory function.
+	 *
+	 * Will override if it's already registered.
+	 *
+	 * @param string $name Internal skin name. Should be all-lowercase (but technically doesn't have
+	 *     to be).
+	 * @param string $displayName For backwards-compatibility with old skin loading system. This is
+	 *     the text used as skin's human-readable name when the 'skinname-<skin>' message is not
+   *     available. It should be the same as the skin name provided in $wgExtensionCredits.
+	 * @param callable $callback Callback that takes the skin name as an argument
 	 * @throws InvalidArgumentException If an invalid callback is provided
 	 */
 	public function register( $name, $displayName, $callback ) {
@@ -149,8 +156,7 @@ class SkinFactory {
 	}
 
 	/**
-	 * Get a legacy skin which uses $wgValidSkinNames
-	 * or autoloading
+	 * Get a legacy skin which uses the autodiscovery mechanism.
 	 *
 	 * @param string $name
 	 * @return Skin|bool false if the skin couldn't be constructed
@@ -191,7 +197,7 @@ class SkinFactory {
 	 */
 	public function makeSkin( $name ) {
 		if ( !isset( $this->factoryFunctions[$name] ) ) {
-			// Check the legacy method of skin loading
+			// Check the legacy autodiscovery method of skin loading
 			$legacy = $this->getLegacySkin( $name );
 			if ( $legacy ) {
 				return $legacy;
-- 
2.20.1