Improve documentation of action=parse (followup Ie4f7324c)

The documentation for action=parse needs clarification, particularly in
light of the changes made in Ie4f7324c which were too hastily merged.

Also, add the RELEASE-NOTES entry missing from Ie4f7324c.

Change-Id: Ia8847f7e99620a9f7af24956d972c882f78aae26

diff --git a/RELEASE-NOTES-1.22 b/RELEASE-NOTES-1.22
index 3832ed1..203880e 100644 (file)
--- a/RELEASE-NOTES-1.22
+++ b/RELEASE-NOTES-1.22
@@ -183,6 +183,8 @@ production.
   honors $wgBlockCIDRLimit. Note any clients passing invalid values to bkip
   will now receive an error, rather than the previous behavior listing all
   user blocks.
+* (bug 48201) action=parse&text=foo now assumes wikitext if no title is given,
+  rather than using the content model of the page "API".
 
 === Languages updated in 1.22===
 

diff --git a/includes/api/ApiParse.php b/includes/api/ApiParse.php
index 89928fe..a369994 100644 (file)
--- a/includes/api/ApiParse.php
+++ b/includes/api/ApiParse.php
@@ -44,9 +44,9 @@ class ApiParse extends ApiBase {
                $params = $this->extractRequestParams();
                $text = $params['text'];
                $title = $params['title'];
-               if ( $title === '' ) {
+               if ( $title === null ) {
                        $titleProvided = false;
-                       // This is the old default value
+                       // A title is needed for parsing, so arbitrarily choose one
                        $title = 'API';
                } else {
                        $titleProvided = true;
@@ -193,10 +193,7 @@ class ApiParse extends ApiBase {
                        // API title, but default to wikitext to keep BC.
                        if ( !$titleProvided && is_null( $model ) ) {
                                $model = CONTENT_MODEL_WIKITEXT;
-                               $this->setWarning(
-                                       "Please set content model with contentmodel parameter. " .
-                                       "Assuming it is $model."
-                               );
+                               $this->setWarning( "No 'title' or 'contentmodel' was given, assuming $model." );
                        }
 
                        try {
@@ -593,9 +590,7 @@ class ApiParse extends ApiBase {
 
        public function getAllowedParams() {
                return array(
-                       'title' => array(
-                               ApiBase::PARAM_DFLT => '',
-                       ),
+                       'title' => null,
                        'text' => null,
                        'summary' => null,
                        'page' => null,
@@ -649,11 +644,13 @@ class ApiParse extends ApiBase {
 
        public function getParamDescription() {
                $p = $this->getModulePrefix();
+               $wikitext = CONTENT_MODEL_WIKITEXT;
                return array(
-                       'text' => 'Wikitext to parse',
+                       'text' => "Text to parse. Use {$p}title or {$p}contentmodel to control the content model",
                        'summary' => 'Summary to parse',
                        'redirects' => "If the {$p}page or the {$p}pageid parameter is set to a redirect, resolve it",
-                       'title' => 'Title of page the text belongs to',
+                       'title' => "Title of page the text belongs to. " .
+                               "If omitted, \"API\" is used as the title with content model $wikitext",
                        'page' => "Parse the content of this page. Cannot be used together with {$p}text and {$p}title",
                        'pageid' => "Parse the content of this page. Overrides {$p}page",
                        'oldid' => "Parse the content of this revision. Overrides {$p}page and {$p}pageid",
@@ -683,27 +680,40 @@ class ApiParse extends ApiBase {
                        ),
                        'pst' => array(
                                'Do a pre-save transform on the input before parsing it',
-                               'Ignored if page, pageid or oldid is used'
+                               "Only valid when used with {$p}text",
                        ),
                        'onlypst' => array(
                                'Do a pre-save transform (PST) on the input, but don\'t parse it',
-                               'Returns the same wikitext, after a PST has been applied. Ignored if page, pageid or oldid is used'
+                               'Returns the same wikitext, after a PST has been applied.',
+                               "Only valid when used with {$p}text",
                        ),
                        'uselang' => 'Which language to parse the request in',
                        'section' => 'Only retrieve the content of this section number',
                        'disablepp' => 'Disable the PP Report from the parser output',
-                       'generatexml' => 'Generate XML parse tree (requires prop=wikitext)',
+                       'generatexml' => "Generate XML parse tree (requires contentmodel=$wikitext)",
                        'preview' => 'Parse in preview mode',
                        'sectionpreview' => 'Parse in section preview mode (enables preview mode too)',
-                       'contentformat' => 'Content serialization format used for the input text',
-                       'contentmodel' => 'Content model of the new content',
+                       'contentformat' => array(
+                               'Content serialization format used for the input text',
+                               "Only valid when used with {$p}text",
+                       ),
+                       'contentmodel' => array(
+                               "Content model of the input text. Default is the model of the " .
+                               "specified ${p}title, or $wikitext if ${p}title is not specified",
+                               "Only valid when used with {$p}text",
+                       ),
                );
        }
 
        public function getDescription() {
+               $p = $this->getModulePrefix();
                return array(
-                       'Parses wikitext and returns parser output',
+                       'Parses content and returns parser output',
                        'See the various prop-Modules of action=query to get information from the current version of a page',
+                       'There are several ways to specify the text to parse:',
+                       "1) Specify a page or revision, using {$p}page, {$p}pageid, or {$p}oldid.",
+                       "2) Specify content explicitly, using {$p}text, {$p}title, and {$p}contentmodel.",
+                       "3) Specify only a summary to parse. {$p}prop should be given an empty value.",
                );
        }