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.

Reply via email to