parser: document what 0/null rev IDs do when given to Parser::parse

This was extremely obscure and tricky to figure out before

Change-Id: Ibdbb669431819eecd34de508735864e977d51021

diff --git a/includes/content/AbstractContent.php b/includes/content/AbstractContent.php
index c82b473..eb9ef85 100644 (file)
--- a/includes/content/AbstractContent.php
+++ b/includes/content/AbstractContent.php
@@ -529,7 +529,7 @@ abstract class AbstractContent implements Content {
         * @since 1.24
         *
         * @param Title $title Context title for parsing
-        * @param int|null $revId Revision ID (for {{REVISIONID}})
+        * @param int|null $revId Revision ID being rendered
         * @param ParserOptions|null $options
         * @param bool $generateHtml Whether or not to generate HTML
         *
@@ -575,7 +575,8 @@ abstract class AbstractContent implements Content {
         * @since 1.24
         *
         * @param Title $title Context title for parsing
-        * @param int|null $revId Revision ID (for {{REVISIONID}})
+        * @param int|null $revId ID of the revision being rendered.
+        *  See Parser::parse() for the ramifications.
         * @param ParserOptions $options
         * @param bool $generateHtml Whether or not to generate HTML
         * @param ParserOutput &$output The output object to fill (reference).

diff --git a/includes/content/Content.php b/includes/content/Content.php
index 2637aa6..8596619 100644 (file)
--- a/includes/content/Content.php
+++ b/includes/content/Content.php
@@ -269,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

diff --git a/includes/content/WikitextContent.php b/includes/content/WikitextContent.php
index 8e5e0a8..70b638b 100644 (file)
--- a/includes/content/WikitextContent.php
+++ b/includes/content/WikitextContent.php
@@ -329,7 +329,8 @@ class WikitextContent extends TextContent {
         * using the global Parser service.
         *
         * @param Title $title
-        * @param int|null $revId Revision to pass to the parser (default: null)
+        * @param int|null $revId ID of the revision being rendered.
+        *  See Parser::parse() for the ramifications. (default: null)
         * @param ParserOptions $options (default: null)
         * @param bool $generateHtml (default: true)
         * @param ParserOutput &$output ParserOutput representing the HTML form of the text,

diff --git a/includes/parser/Parser.php b/includes/parser/Parser.php
index b643c3f..f982de4 100644 (file)
--- a/includes/parser/Parser.php
+++ b/includes/parser/Parser.php
@@ -530,7 +530,10 @@ class Parser {
         * @param ParserOptions $options
         * @param bool $linestart
         * @param bool $clearState
-        * @param int|null $revid Number to pass in {{REVISIONID}}
+        * @param int|null $revid ID of the revision being rendered. This is used to render
+        *  REVISION* magic words. 0 means that any current revision will be used. Null means
+        *  that {{REVISIONID}}/{{REVISIONUSER}} will be empty and {{REVISIONTIMESTAMP}} will
+        *  use the current timestamp.
         * @return ParserOutput A ParserOutput
         * @return-taint escaped
         */

diff --git a/tests/phpunit/includes/parser/ParserMethodsTest.php b/tests/phpunit/includes/parser/ParserMethodsTest.php
index 651c871..4175ead 100644 (file)
--- a/tests/phpunit/includes/parser/ParserMethodsTest.php
+++ b/tests/phpunit/includes/parser/ParserMethodsTest.php
@@ -234,6 +234,7 @@ class ParserMethodsTest extends MediaWikiLangTestCase {
                $po = new ParserOptions( $frank );
 
                yield 'current' => [ $text, $po, 0, 'user:CurrentAuthor;id:200;time:20160606000000;' ];
+               yield 'current' => [ $text, $po, null, 'user:;id:;time:' ];
                yield 'current with ID' => [ $text, $po, 200, 'user:CurrentAuthor;id:200;time:20160606000000;' ];
 
                $text = '* user:{{REVISIONUSER}};id:{{REVISIONID}};time:{{REVISIONTIMESTAMP}};';