On 29 December 2014 at 03:52, Andrei Alexandrescu via Digitalmars-d <digitalmars-d@puremagic.com> wrote: > On 12/28/14 6:43 PM, Manu via Digitalmars-d wrote: >> >> On 27 December 2014 at 02:21, Andrei Alexandrescu via Digitalmars-d >> <digitalmars-d@puremagic.com> wrote: >>> >>> On 12/25/14 5:18 PM, Mike Parker wrote: >>>> >>>> >>>> On 12/26/2014 9:48 AM, Manu via Digitalmars-d wrote: >>>> >>>>> >>>>> Ironically, the string and algorithm functions are probably the worst >>>>> offenders, but coincidentally, there is a high chance that these are >>>>> the first functions anyone will ever reach for, so they present a >>>>> terrible first impression. >>>>> >>>> >>>> +1 >>>> >>>> When I first made the move from D1 to D2, this caused me no end of >>>> frustration. The docs were quite unhelpful in this regard. It irked me >>>> enough that I wrote a rant about it on my old blog. It doesn't bother me >>>> anymore, so I haven't thought about it in years. This post brings it >>>> back. >>> >>> >>> >>> I thought the std.algorithm stuff is decently documented. What would be >>> the >>> major pain points? -- Andrei >>> >> >> The first line of text respectively: >> >> C#: >> public static void Sort<T>(T[] array) >> >> D: >> SortedRange!(Range, less) sort(alias less = "a < b", SwapStrategy ss >> = SwapStrategy.unstable, Range)(Range r) if ((ss == >> SwapStrategy.unstable && (hasSwappableElements!Range || >> hasAssignableElements!Range) || ss != SwapStrategy.unstable && >> hasAssignableElements!Range) && isRandomAccessRange!Range && >> hasSlicing!Range && hasLength!Range); >> >> >> I'm sure you can see the problem... > > > Thanks, following your feedback I have recently submitted an enhancement > request. Just for the sake of humblebragging, C#'s sort works only on arrays > whereas D's sort (a) returns a statically-informed sorted range with > specific primitives, (b) is configurable to use a custom predicate, (c) > allows stability selection, (d) works for any range satisfying certain > requirements. Yay...? :o) > > Andrei >
The new layout solves half the problem in that it hides the template constraints. http://dlang.org/library/std/algorithm/sort.html Shouldn't our focus also be to get the new layout out of "preview" mode and do our standardization of documentation from there? By the way, I would also nick pick on top of Manu's suggestion that the short description for sort() is just "Sorts". I'm sure this can be expanded to more than one word and less than twelve. Iain.