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

diff --git a/includes/XmlJsCode.php b/includes/XmlJsCode.php
index d1cd037..35a0607 100644 (file)
--- 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 6b4281f..01adeab 100644 (file)
--- 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 4c011be..f0fcd7d 100644 (file)
--- 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 1d1df6a..3273046 100644 (file)
--- 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 15833dc..31cfa70 100644 (file)
--- 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.