From c689fd2e4cc14bedeaa4303aa9958f95d96a2779 Mon Sep 17 00:00:00 2001
From: Timo Tijhof <krinklemail@gmail.com>
Date: Mon, 17 Jul 2017 20:24:32 -0500
Subject: [PATCH] doc: Fix a few Example docs for PHP classes

* "@example" is specifically for creating entries on the "Examples"
  page produced by Doxygen, which is not specific to individual classes
  or methods, but rather is meant to be about the software as a whole.
  There are currently four entries produced there, and they are all broken:
  - .../src/includes/rcfeed/RedisPubSubFeedEngine.php (unnamed example, broken)
  - .../src/tests/phpunit/MediaWikiTestCase.php (unnamed example)
  - 42 (empty page named "42")
  - user (empty page named "user")

* Remove usage and replace with either a regular paragraph that is
  part of the member/method/class description, or for code examples,
  use "@par" to create a sub heading, and then a @code-@endcode block.

Change-Id: I52c937fef4b377173f6c4dbad9dc4a9f8beae4ee
---
 includes/XmlJsCode.php                    |  9 +++---
 includes/libs/MemoizedCallable.php        | 37 ++++++++++++-----------
 includes/rcfeed/RedisPubSubFeedEngine.php |  4 ++-
 includes/specials/SpecialRedirect.php     |  6 ++--
 tests/phpunit/MediaWikiTestCase.php       |  6 ++--
 5 files changed, 35 insertions(+), 27 deletions(-)

diff --git a/includes/XmlJsCode.php b/includes/XmlJsCode.php
index d1cd037c98..35a06071a2 100644
--- a/includes/XmlJsCode.php
+++ b/includes/XmlJsCode.php
@@ -23,11 +23,12 @@
  * interpret a given string as being a JavaScript expression, instead of string
  * data.
  *
- * Example:
+ * @par Example:
+ * @code
+ *     Xml::encodeJsVar( new XmlJsCode( 'a + b' ) );
+ * @encode
  *
- *    Xml::encodeJsVar( new XmlJsCode( 'a + b' ) );
- *
- * Returns "a + b".
+ * This returns "a + b".
  *
  * @note As of 1.21, XmlJsCode objects cannot be nested inside objects or arrays. The sole
  *       exception is the $args argument to Xml::encodeJsCall() because Xml::encodeJsVar() is
diff --git a/includes/libs/MemoizedCallable.php b/includes/libs/MemoizedCallable.php
index 6b4281fb96..01adeab5fc 100644
--- a/includes/libs/MemoizedCallable.php
+++ b/includes/libs/MemoizedCallable.php
@@ -1,4 +1,24 @@
 <?php
+/**
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ * http://www.gnu.org/copyleft/gpl.html
+ *
+ * @file
+ * @author Ori Livneh
+ */
+
 /**
  * APC-backed and APCu-backed function memoization
  *
@@ -18,23 +38,6 @@
  * MemoizedCallable::call( 'range', array( 5, 8 ) );  // same
  * @endcode
  *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
- * http://www.gnu.org/copyleft/gpl.html
- *
- * @file
- * @author Ori Livneh
  * @since 1.27
  */
 class MemoizedCallable {
diff --git a/includes/rcfeed/RedisPubSubFeedEngine.php b/includes/rcfeed/RedisPubSubFeedEngine.php
index 4c011be2cd..f0fcd7da74 100644
--- a/includes/rcfeed/RedisPubSubFeedEngine.php
+++ b/includes/rcfeed/RedisPubSubFeedEngine.php
@@ -27,11 +27,13 @@
  * 'rc'. If the URI contains a query string, its parameters will be parsed
  * as RedisConnectionPool options.
  *
- * @example
+ * @par Example:
+ * @code
  * $wgRCFeeds['redis'] = array(
  *      'formatter' => 'JSONRCFeedFormatter',
  *      'uri'       => "redis://127.0.0.1:6379/rc.$wgDBname",
  * );
+ * @encode
  *
  * @since 1.22
  */
diff --git a/includes/specials/SpecialRedirect.php b/includes/specials/SpecialRedirect.php
index 1d1df6a043..3273046f57 100644
--- a/includes/specials/SpecialRedirect.php
+++ b/includes/specials/SpecialRedirect.php
@@ -33,16 +33,18 @@ class SpecialRedirect extends FormSpecialPage {
 	/**
 	 * The type of the redirect (user/file/revision)
 	 *
+	 * Example value: `'user'`
+	 *
 	 * @var string $mType
-	 * @example 'user'
 	 */
 	protected $mType;
 
 	/**
 	 * The identifier/value for the redirect (which id, which file)
 	 *
+	 * Example value: `'42'`
+	 *
 	 * @var string $mValue
-	 * @example '42'
 	 */
 	protected $mValue;
 
diff --git a/tests/phpunit/MediaWikiTestCase.php b/tests/phpunit/MediaWikiTestCase.php
index 15833dc535..31cfa7042a 100644
--- a/tests/phpunit/MediaWikiTestCase.php
+++ b/tests/phpunit/MediaWikiTestCase.php
@@ -640,8 +640,8 @@ abstract class MediaWikiTestCase extends PHPUnit_Framework_TestCase {
 	 * The key is added to the array of globals that will be reset afterwards
 	 * in the tearDown().
 	 *
-	 * @example
-	 * <code>
+	 * @par Example
+	 * @code
 	 *     protected function setUp() {
 	 *         $this->setMwGlobals( 'wgRestrictStuff', true );
 	 *     }
@@ -656,7 +656,7 @@ abstract class MediaWikiTestCase extends PHPUnit_Framework_TestCase {
 	 *     }
 	 *
 	 *     function testQuux() {}
-	 * </code>
+	 * @endcode
 	 *
 	 * @param array|string $pairs Key to the global variable, or an array
 	 *  of key/value pairs.
-- 
2.20.1