From 26b1ba39898da08f2ec1efe3c8ee7376cd117ad4 Mon Sep 17 00:00:00 2001 From: Aaron Schulz Date: Thu, 27 Jun 2019 00:17:06 -0700 Subject: [PATCH] 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 --- includes/content/AbstractContent.php | 5 +++-- includes/content/Content.php | 3 ++- includes/content/WikitextContent.php | 3 ++- includes/parser/Parser.php | 5 ++++- tests/phpunit/includes/parser/ParserMethodsTest.php | 1 + 5 files changed, 12 insertions(+), 5 deletions(-) diff --git a/includes/content/AbstractContent.php b/includes/content/AbstractContent.php index c82b4734ca..eb9ef850b4 100644 --- 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 2637aa6929..8596619d13 100644 --- 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 8e5e0a8305..70b638b4b4 100644 --- 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 b643c3f09c..f982de4d6d 100644 --- 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 651c87161c..4175eadb57 100644 --- 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}};'; -- 2.20.1