drupal_sort_weight() docs are a bit obscure and don't mention default weight

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.

Here is patch.

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'.

Changed after feedback from #3.

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

Also check for spaces at the end of lines.

With feedback from #5

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

Ported.

Looks good, thanks! Committed to 7.x.