On Sunday, 15 March 2015 at 10:53:21 UTC, Marc Schütz wrote:
I hope you'll get better!
Thanks. On the mend, but it takes time...
3. I have said so before (the GroupBy docs) - standard library
documentation is 'perfectly clear' if you have a technical
mindset and are used to reading formalisms, but it is
horrendously intimidating if not (which applies to many
people). We need more examples, and they should put the use
in context rather than just being tiny fragments - ie show how
to do something useful with the function (cf python docs).
There should also be a guide to functions writing from point
of what one wants to achieve. toLower in std.string, but I
need to go to std.ascii for doing the same thing to a
character. Eminently logical, but not obvious if you don't
know where to look.
It seems the accessibility/discoverability of string handling
is a common complaint. People expect certain functions to be
available for strings, like startsWith, trim/ltrim/rtrim,
repeat, maybe even regex matching. Now, these things are all
available in other parts of Phobos, or easily implementable
using components from all over the standard library, but a
beginner won't know this, and even if, it's inconvenient.
Maybe we should add the most common functions to `std.string`?
Either as aliases or re-exports, or even (re)implement them
there with the appropriate semantics if necessary. For example,
people would expect a hypothetical `std.string.repeat` to be
eager, whereas `std.range.repeat("hello").take(5)` is lazy.
Some operations may also decay to ranges of `dchar`, but we'd
want to preserve the string type.
No opinion on this myself, but aliases have a cost in terms of
confusion (what's the difference? err there is none) whereas
there may be some value in reimplementation with appropriate
semantics at some future point.
But I think the closest sticking point is not lack of order in
library organisation - just that the documents are written from
the perspective of the library writer and there is currently no
coherent, complete, and polished set of documents primarily
oriented to 'how do I accomplish this task'. I understand why
that is, but if one identifies a problem one can work away at it
slowly over time.