Should this work?

[H. S. Teoh]

On Fri, Jan 10, 2014 at 01:34:46AM +0000, Adam D. Ruppe wrote:
[...]
> Some code differences from the old days:
> 
> * before: converting to and from string was in std.string. Functions
> like toInt, toString, etc. Nowadays, this is all done with
> std.conv.to. The new way is way cool, but a newbie's first place to
> look might be for std.string.toString rather than std.conv.to!string.

Right, so it should be mentioned in std.string.

But probably your idea of more concept-oriented overview pages is
better. It doesn't seem like the right solution to just insert
hyperlinks to std.conv in every other Phobos module.


> * before: some char type stuff was in std.string (and the rest in
> std.ctype IIRC). Now, it is in std.ascii and std.uni.

Yeah, this is one of the things I found annoying. Sure I understand why
std.ascii needs to be different from std.uni, but then you have stuff
split across std.string, std.ascii, std.uni, and std.utf -- what's the
diff between std.utf and std.uni?! (Yes I know what the diff is, the
point is that it looks silly to a newcomer.)


> * before: the signatures were char[] foo(char[]). Nowadays, it is S
> foo(S)(S s) if(isSomeString!S)... so much wordier! Better
> functionality, but omg it can be a pain to read and surely
> intimidating for newbs.

Sig constraints seriously need to be formatted differently from the way
they are right now, which is an unreadable blob of obtuse text. Take
std.algorithm.makeIndex, for example. How do you even *read* that
mess??! It's 6 lines of dense, *bolded* text (on my browser anyway,
YMMV), and it's not even clear that it's actually two overloads. I have
trouble telling what exactly it returns, and where its parameter lists
start and end. Nor what the sig constraints actually mean.

Actually, this particular case seems to be a prime example of the sig
constraint vs. static if idea I had in another post (i.e., sig
constraints should only define the scope of the overload, and type
requirements on arguments within that scope should be inside static ifs
in the body of the function / template). From what I can see, makeIndex
really should be in a *single* template, probably with no sig
constraints (or only very simple ones), and everything else should be
inside the template body as static if blocks. Whatever is unclear from
the outer sig constraints should be explained in the text of the ddoc.
Users shouldn't be expected to be able to parse sig constraints that are
really Phobos internal implementation details.


> I think things are generally improved as for functionality and
> consistency, but the docs are more debatable.

I agree, functionality is more unified and consistent, but the docs are
very newbie-unfriendly.


T

-- 
Why can't you just be a nonconformist like everyone else? -- YHL