From 7d964e567a16915478483c6684d5008025ca4bb7 Mon Sep 17 00:00:00 2001
From: TTO <at.light@live.com.au>
Date: Mon, 23 Apr 2018 01:44:33 +0000
Subject: [PATCH] Fix unclear comments on various ChangeTags functions

These functions tell you whether *a user* can perform the relevant
actions. They are not meant to be used by extensions, except when
the extension is performing these actions on behalf of a user.

Change-Id: I8437ec2d66c151f504755964e20fda808d35de3b
---
 includes/changetags/ChangeTags.php | 32 ++++++++++++++++++++++++------
 1 file changed, 26 insertions(+), 6 deletions(-)

diff --git a/includes/changetags/ChangeTags.php b/includes/changetags/ChangeTags.php
index 5b6088d59f..b64f85a9b4 100644
--- a/includes/changetags/ChangeTags.php
+++ b/includes/changetags/ChangeTags.php
@@ -32,6 +32,9 @@ class ChangeTags {
 	 */
 	const MAX_DELETE_USES = 5000;
 
+	/**
+	 * A list of tags defined and used by MediaWiki itself.
+	 */
 	private static $definedSoftwareTags = [
 		'mw-contentmodelchange',
 		'mw-new-redirect',
@@ -474,9 +477,12 @@ class ChangeTags {
 	 * Is it OK to allow the user to apply all the specified tags at the same time
 	 * as they edit/make the change?
 	 *
+	 * Extensions should not use this function, unless directly handling a user
+	 * request to add a tag to a revision or log entry that the user is making.
+	 *
 	 * @param array $tags Tags that you are interested in applying
-	 * @param User|null $user User whose permission you wish to check, or null if
-	 * you don't care (e.g. maintenance scripts)
+	 * @param User|null $user User whose permission you wish to check, or null to
+	 * check for a generic non-blocked user with the relevant rights
 	 * @return Status
 	 * @since 1.25
 	 */
@@ -541,10 +547,13 @@ class ChangeTags {
 	 * Is it OK to allow the user to adds and remove the given tags tags to/from a
 	 * change?
 	 *
+	 * Extensions should not use this function, unless directly handling a user
+	 * request to add or remove tags from an existing revision or log entry.
+	 *
 	 * @param array $tagsToAdd Tags that you are interested in adding
 	 * @param array $tagsToRemove Tags that you are interested in removing
-	 * @param User|null $user User whose permission you wish to check, or null if
-	 * you don't care (e.g. maintenance scripts)
+	 * @param User|null $user User whose permission you wish to check, or null to
+	 * check for a generic non-blocked user with the relevant rights
 	 * @return Status
 	 * @since 1.25
 	 */
@@ -589,11 +598,15 @@ class ChangeTags {
 	 * Adds and/or removes tags to/from a given change, checking whether it is
 	 * allowed first, and adding a log entry afterwards.
 	 *
-	 * Includes a call to ChangeTag::canUpdateTags(), so your code doesn't need
+	 * Includes a call to ChangeTags::canUpdateTags(), so your code doesn't need
 	 * to do that. However, it doesn't check whether the *_id parameters are a
 	 * valid combination. That is up to you to enforce. See ApiTag::execute() for
 	 * an example.
 	 *
+	 * Extensions should generally avoid this function. Call
+	 * ChangeTags::updateTags() instead, unless directly handling a user request
+	 * to add or remove tags from an existing revision or log entry.
+	 *
 	 * @param array|null $tagsToAdd If none, pass array() or null
 	 * @param array|null $tagsToRemove If none, pass array() or null
 	 * @param int|null $rc_id The rc_id of the change to add the tags to
@@ -721,7 +734,8 @@ class ChangeTags {
 	 * @throws MWException When unable to determine appropriate JOIN condition for tagging
 	 */
 	public static function modifyDisplayQuery( &$tables, &$fields, &$conds,
-										&$join_conds, &$options, $filter_tag = '' ) {
+		&$join_conds, &$options, $filter_tag = ''
+	) {
 		global $wgUseTagFilter;
 
 		// Normalize to arrays
@@ -1057,6 +1071,9 @@ class ChangeTags {
 	/**
 	 * Is it OK to allow the user to create this tag?
 	 *
+	 * Extensions should NOT use this function. In most cases, a tag can be
+	 * defined using the ListDefinedTags hook without any checking.
+	 *
 	 * @param string $tag Tag that you are interested in creating
 	 * @param User|null $user User whose permission you wish to check, or null if
 	 * you don't care (e.g. maintenance scripts)
@@ -1092,6 +1109,9 @@ class ChangeTags {
 	/**
 	 * Creates a tag by adding a row to the `valid_tag` table.
 	 *
+	 * Extensions should NOT use this function; they can use the ListDefinedTags
+	 * hook instead.
+	 *
 	 * Includes a call to ChangeTag::canDeleteTag(), so your code doesn't need to
 	 * do that.
 	 *
-- 
2.20.1