Merge "OutputPage: Add visibility to various methods & do some micro-optimizations"

[lhc/web/wiklou.git] / includes / content / Content.php

diff --git a/includes/content/Content.php b/includes/content/Content.php
index 000bff2..8596619 100644 (file)
--- a/includes/content/Content.php
+++ b/includes/content/Content.php
@@ -77,6 +77,9 @@ interface Content {
         *
         * @since 1.21
         *
+        * @deprecated since 1.33 use getText() for TextContent instances.
+        *             For other content models, use specialized getters.
+        *
         * @return mixed The native representation of the content. Could be a
         *    string, a nested array structure, an object, a binary blob...
         *    anything, really.
@@ -199,9 +202,11 @@ interface Content {
         *
         * - Will return false if $that is null.
         * - Will return true if $that === $this.
-        * - Will return false if $that->getModel() != $this->getModel().
-        * - Will return false if $that->getNativeData() is not equal to $this->getNativeData(),
-        *   where the meaning of "equal" depends on the actual data model.
+        * - Will return false if $that->getModel() !== $this->getModel().
+        * - Will return false if get_class( $that ) !== get_class( $this )
+        * - Should return false if $that->getModel() == $this->getModel() and
+        *     $that is not semantically equivalent to $this, according to
+        *     the data model defined by $this->getModel().
         *
         * Implementations should be careful to make equals() transitive and reflexive:
         *
@@ -241,6 +246,8 @@ interface Content {
         * that it's also in a countable location (e.g. a current revision in the
         * main namespace).
         *
+        * @see SlotRoleHandler::supportsArticleCount
+        *
         * @since 1.21
         *
         * @param bool|null $hasLinks If it is known whether this content contains
@@ -262,7 +269,8 @@ interface Content {
         *       may call ParserOutput::recordOption() on the output object.
         *
         * @param Title $title The page title to use as a context for rendering.
-        * @param int|null $revId Optional revision ID being rendered.
+        * @param int|null $revId ID of the revision being rendered.
+        *  See Parser::parse() for the ramifications. (default: null)
         * @param ParserOptions|null $options Any parser options.
         * @param bool $generateHtml Whether to generate HTML (default: true). If false,
         *        the result of calling getText() on the ParserOutput object returned by
@@ -284,13 +292,8 @@ interface Content {
         * made to replace information about the old content with information about
         * the new content.
         *
-        * This default implementation calls
-        * $this->getParserOutput( $content, $title, null, null, false ),
-        * and then calls getSecondaryDataUpdates( $title, $recursive ) on the
-        * resulting ParserOutput object.
-        *
-        * Subclasses may implement this to determine the necessary updates more
-        * efficiently, or make use of information about the old content.
+        * @deprecated since 1.32, call and override
+        *   ContentHandler::getSecondaryDataUpdates instead.
         *
         * @note Implementations should call the SecondaryDataUpdates hook, like
         *   AbstractContent does.
@@ -357,6 +360,8 @@ interface Content {
         * Returns whether this Content represents a redirect.
         * Shorthand for getRedirectTarget() !== null.
         *
+        * @see SlotRoleHandler::supportsRedirects
+        *
         * @since 1.21
         *
         * @return bool
@@ -481,8 +486,10 @@ interface Content {
         * the current state of the database.
         *
         * @since 1.21
+        * @deprecated since 1.32, call and override
+        *   ContentHandler::getDeletionUpdates instead.
         *
-        * @param WikiPage $page The deleted page
+        * @param WikiPage $page The page the content was deleted from.
         * @param ParserOutput|null $parserOutput Optional parser output object
         *    for efficient access to meta-information about the content object.
         *    Provide if you have one handy.