Documentation Bug in function sort() of DataObjectSet

[meeque]

The documentation of DataObjectSet::sort() states: "Returns a new DataObjectSet? of the sorted array" But the function does not return anything at all. Instead it sorts the the DataObjectSet? in place.

This may be confusing for people trying to use this function. I can think of three different variants to fix this issue:

1. Only modify the documentation of the function, so it does not mention a return value any more. Instead it should state that the function sorts the DataObjectSet? in place.

2. Modify the function, so it returns a reference to the DataObjectSet? (i.e. $this) after it is sortet. Also modify the documentation, so it states that the function has side-effects on the DataObjectSet? it is called on. Do not say that it returns a *new* DataObjectSet?.

3. Modify the function, so it creates a new copy of the DataObjectSet?, sorts it, and returns it. In this case, the function should not have any side-effects on the original DataObjectSet? (i.e. $this).

If anyone tells me, which of the variants above is prefered, I can submit a patch. I'd opt for 1 or 2.

-- Michael Riedel, Xebidy Strategic Design

PS: I found this issue in Silverstripe 2.1, but it seems to exist in the current svn trunk, too.