On http://api.drupal.org/api/drupal/core%21includes%21common.inc/function/d... :

> Sorts a structured array by 'weight' key (no # prefix).

On http://api.drupal.org/api/drupal/includes!common.inc/function/drupal_sor... :

> Function used by uasort to sort structured arrays by weight, without the property weight prefix.

In both cases, what's the prefix thing about?

This function doc should say, in approximate order:

- this is a callback for uasort() (which I presume needs the () so it can be rendered as a link to PHP docs)
- it sorts arrays where each item (itself an array) has a ['weight'] property
- if an element doesn't have that property, its weight it taken as being 0

Also, now that API has string references, I don't think the D8 docs need to explicitly list the functions that make use of this.

Files: 
CommentFileSizeAuthor
#10 core-element_info_property-doc-fix-1673380-5-port.patch962 bytesmarcin.wosinek
PASSED: [[SimpleTest]]: [MySQL] 39,342 pass(es).
[ View ]
#7 core-element_info_property-doc-fix-1673380-5.patch1.04 KBmarcin.wosinek
PASSED: [[SimpleTest]]: [MySQL] 37,245 pass(es).
[ View ]
#4 core-element_info_property-doc-fix-1673380-3.patch1.04 KBmarcin.wosinek
PASSED: [[SimpleTest]]: [MySQL] 37,214 pass(es).
[ View ]
#2 core-element_info_property-doc-fix-1673380.patch959 bytesmarcin.wosinek
PASSED: [[SimpleTest]]: [MySQL] 37,103 pass(es).
[ View ]

Comments

jhodgdon’s picture

Thanks for this report! Some thoughts:

- The note about the # prefix is there so that you don't think you can use it to sort form elements by their '#weight' array element. Obviously, that was a bit confusing, so let's get that reworded.
- I agree that the list in D8 of some of the functions that use this callback is not really necessary. How about we just change it to say "Callback for uasort() used in various functions.".
- I also agree the 0 default weight should be mentioned in the documentation.
- I also agree that the documentation could be better written in general.
- The documentation should also use the term "element" to refer to an array value that corresponds to a particular key (I think it is using "key" incorrectly in a couple of places).

So let's start with a D8 patch to clean up the documentation there, and then port to D7.

marcin.wosinek’s picture

Status:Active» Needs review
StatusFileSize
new959 bytes
PASSED: [[SimpleTest]]: [MySQL] 37,103 pass(es).
[ View ]

Here is patch.

jhodgdon’s picture

Status:Needs review» Needs work

Looks pretty good! There's a spot of English grammar and spelling that needs to be fixed:

+ *   that optionally include a 'weight' element. For items without 'weight'
+ *   will be used deafult value 0.

The second sentence should say:

For items without a 'weight' element, a default value of 0 will be used.

Also I think in the first line, it shouldn't say "no # prefix is needed" -- that is not really clearing up the confusion I think. I think it should say something that *does* clear up the confusion, in a new paragraph. Something like:

Note that the sorting is by the 'weight' array element, not by the render element property '#weight'.

marcin.wosinek’s picture

Status:Needs work» Needs review
StatusFileSize
new1.04 KB
PASSED: [[SimpleTest]]: [MySQL] 37,214 pass(es).
[ View ]

Changed after feedback from #3.

jhodgdon’s picture

Status:Needs review» Needs work

Better! Two little fixes and I think it will be ready:
- default is still misspelled.
- The first line needs "the" (... by the 'weight...)

jhodgdon’s picture

Also check for spaces at the end of lines.

marcin.wosinek’s picture

Status:Needs work» Needs review
StatusFileSize
new1.04 KB
PASSED: [[SimpleTest]]: [MySQL] 37,245 pass(es).
[ View ]

With feedback from #5

joachim’s picture

Status:Needs review» Reviewed & tested by the community

Looks good to me.

jhodgdon’s picture

Version:8.x-dev» 7.x-dev
Status:Reviewed & tested by the community» Patch (to be ported)

Thanks! Committed to 8.x. Patch doesn't apply to 7.x, so we need a reroll/port.

marcin.wosinek’s picture

Status:Patch (to be ported)» Needs review
StatusFileSize
new962 bytes
PASSED: [[SimpleTest]]: [MySQL] 39,342 pass(es).
[ View ]

Ported.

jhodgdon’s picture

Status:Needs review» Fixed

Looks good, thanks! Committed to 7.x.

Automatically closed -- issue fixed for 2 weeks with no activity.