Page MenuHomePhabricator

Improve documentation of API's "dir" parameter
Open, LowPublic

Description

Go to
https://en.wikipedia.org/w/api.php
and search for "dir " (with the space). There will be 43 results. Of these, only a few (9 results) have an explanation of the meaning of "newer" and "older", like this:

rvdir - In which direction to enumerate (enum)
   newer - List oldest first. Note: rvstart has to be before rvend.
   older - List newest first (default). Note: rvstart has to be later than rvend.
  One value: newer, older
  Default: older

The others are documented like so:

afldir - The direction in which to enumerate
         One value: newer, older
         Default: older

This could be improved to match the first example above.

It seems includes/api/ApiQueryBase.php has a function getDirectionDescription to help with this.

Details

Reference
bz56860

Event Timeline

bzimport raised the priority of this task from to Low.Nov 22 2014, 2:26 AM
bzimport set Reference to bz56860.
He7d3r created this task.Nov 10 2013, 2:53 PM

cpt.at.work wrote:

I would like to work on this bug. Please assign it to me.

Created attachment 16870
The attached file improves documentation of API's "dir" parameter (which accept values older, newer)

'dir' parameter which accepts as values newer, oldest is now properly documented in several places on the attached XML file.

Attached:

Qgil added a comment.Oct 28 2014, 2:39 PM

Thank you dkontotasiu. Just wondering, wouldn't it be better to submit a patch for review?

(In reply to Quim Gil from comment #3)

Just wondering, wouldn't it be better to submit a patch for review?

Very much so. A hand-edited version of the auto-generated documentation (that was redone completely in Gerrit change 161093) isn't likely to get results.

Anomie updated the task description. (Show Details)Jan 7 2015, 3:37 PM
Anomie set Security to None.
Anomie moved this task from Unsorted to Needs Code on the MediaWiki-API board.Feb 19 2015, 6:48 PM
He7d3r updated the task description. (Show Details)Jan 19 2016, 12:04 PM
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptJan 19 2016, 12:04 PM
Aklapper removed D_konto as the assignee of this task.Dec 15 2016, 3:17 PM

@D_konto: I am resetting the assignee of this task because there have been no signs of progress lately (please correct me if I'm wrong).
Please claim this task again when you plan to submit your patch to Gerrit. Thanks!

Restricted Application added a subscriber: TerraCodes. · View Herald TranscriptDec 15 2016, 3:17 PM

I was trying to reproduce the bug. I visited https://en.wikipedia.org/w/api.php page. I'm not sure which parameters to use in the URL to search for "dir ". Can someone please help me? Am I wrong somewhere in using the params to search?

The page api.php has changed a lot since MediaWiki 1.22. You can still reproduce it on any wiki still running the old version. E.g.: http://brlcad.org/w/api.php

Although looking back at this bug, it might be better to take care of this as part of a larger standardization of "dir" parameters as a distinct type so they all take the same set of values.

Now I am using mediawiki 1.30. so Is it needed to me to degrade to mediawiki 1.22. to work on this issue ?

No. Just because code is changed and included in the next version to be released at that time (1.22) does not mean that we remove all code changes again for the the versions released afterwards (>=1.23). ;-)

Gopavasanth added a comment.EditedJan 15 2018, 9:36 AM

I found 23 dir's are in api.php :

The direction in which to list                
One value: ascending, descending
Default: ascending

How can I write the description for the ascending and descending ?

By making them use the existing string api-help-param-direction? I am not sure what your question is.

Gopavasanth added a comment.EditedJan 27 2018, 1:57 PM

I am trying to improve this document so how to change the following code into new formate?

The direction in which to list                
One value: ascending, descending
Default: ascending

This code is found in many dir's in this api.php

The page api.php has changed a lot since MediaWiki 1.22. You can still reproduce it on any wiki still running the old version. E.g.: http://brlcad.org/w/api.php

@He7d3r went to the link given but could find only 35 matches of "dir " and also many of them have a different kind of documentation rather than provided in the description such as newer, older it appears to be ascending, descending etc and more of them doesn't match that of them provided in description above?

@He7d3r I'm Diksha and I'm an outreachy applicant. Can I take up this task?

Restricted Application added a project: Core Platform Team. · View Herald TranscriptOct 22 2019, 8:52 PM

Hi @He7d3r I have made some changes in the XML file. Kindly review.

Reedy updated the task description. (Show Details)Oct 23 2019, 11:16 AM
Reedy added a comment.EditedOct 23 2019, 11:32 AM

Hi @He7d3r I have made some changes in the XML file. Kindly review.

Thanks for your attempt, however unfortunately trying to review changes in a 5000+ line XML file is a non starter. It's not a useful format, provides no easy way to know what you changed etc.

Please see https://www.mediawiki.org/wiki/Gerrit/Tutorial on how to setup and work with our version control to submit a patch. It would likely be changes to includes/api/i18n/en.json and the PHP files in the includes/api folder of MW Core

However, looking at the API's en.json...

	"api-help-param-direction": "In which direction to enumerate:\n;newer:List oldest first. Note: $1start has to be before $1end.\n;older:List newest first (default). Note: $1start has to be later than $1end.",

Which presents like

And others that still use (which is like @He7d3r's original issue

	"apihelp-query+allcategories-param-dir": "Direction to sort in.",

And used implicitly, no override

			'dir' => [
				ApiBase::PARAM_DFLT => 'ascending',
				ApiBase::PARAM_TYPE => [
					'ascending',
					'descending'
				]
			],

Versus the ones above that use api-help-param-direction.. As per my original image, there's also deleted revisions

			'dir' => [
				ApiBase::PARAM_TYPE => [
					'newer',
					'older'
				],
				ApiBase::PARAM_DFLT => 'older',
				ApiBase::PARAM_HELP_MSG => 'api-help-param-direction',
			],

But there is context relating to the 'dir'. api-help-param-direction can only be used when the direction is time related

A quick find in the API en.json file for param-dir gives 25 results:

	"apihelp-query+allcategories-param-dir": "Direction to sort in.",
	"apihelp-query+allfileusages-param-dir": "The direction in which to list.",
	"apihelp-query+allimages-param-dir": "The direction in which to list.",
	"apihelp-query+alllinks-param-dir": "The direction in which to list.",
	"apihelp-query+allpages-param-dir": "The direction in which to list.",
	"apihelp-query+allredirects-param-dir": "The direction in which to list.",
	"apihelp-query+alltransclusions-param-dir": "The direction in which to list.",
	"apihelp-query+allusers-param-dir": "Direction to sort in.",
	"apihelp-query+backlinks-param-dir": "The direction in which to list.",
	"apihelp-query+categories-param-dir": "The direction in which to list.",
	"apihelp-query+categorymembers-param-dir": "In which direction to sort.",
	"apihelp-query+duplicatefiles-param-dir": "The direction in which to list.",
	"apihelp-query+embeddedin-param-dir": "The direction in which to list.",
	"apihelp-query+filearchive-param-dir": "The direction in which to list.",
	"apihelp-query+images-param-dir": "The direction in which to list.",
	"apihelp-query+imageusage-param-dir": "The direction in which to list.",
	"apihelp-query+iwbacklinks-param-dir": "The direction in which to list.",
	"apihelp-query+iwlinks-param-dir": "The direction in which to list.",
	"apihelp-query+langbacklinks-param-dir": "The direction in which to list.",
	"apihelp-query+langlinks-param-dir": "The direction in which to list.",
	"apihelp-query+links-param-dir": "The direction in which to list.",
	"apihelp-query+pageswithprop-param-dir": "In which direction to sort.",
	"apihelp-query+templates-param-dir": "The direction in which to list.",
	"apihelp-query+watchlistraw-param-dir": "The direction in which to list.",
	"api-help-param-direction": "In which direction to enumerate:\n;newer:List oldest first. Note: $1start has to be before $1end.\n;older:List newest first (default). Note: $1start has to be later than $1end.",

24 of those may be the ones that need more context adding. It could be done by modifying each of the messages to include more information, or if there's some commonality to the "dir" context (like with the date ones), a reusable message could potentially be introduced to be shared

Any modifications to en.json that add $1 (for example) to a message, will likely require updates to qqq.json too to document this parameter

Qgil removed a subscriber: Qgil.Oct 23 2019, 3:07 PM

@Dikshagupta99: Hi! You assigned this task to yourself a few weeks ago. Is there anything that others could help with? Thanks a lot!

Hi, I have sent an updated XML file earlier. Currently, I'm making some changes in that XML file. Thank you!

Hi, I have sent an updated XML file earlier. Currently, I'm making some changes in that XML file. Thank you!

As instructed in T58860#617811 and T58860#5598289, you should be submitting a patch in Gerrit rather than attaching a hand-edited XML file to this task. See https://www.mediawiki.org/wiki/Gerrit for documentation links.

Dikshagupta99 removed Dikshagupta99 as the assignee of this task.Fri, Dec 6, 6:08 PM