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
