On 2014-01-10 12:36, FreeSlave wrote:
The current state of Phobos documentation is terrible in some moments. Many types and functions are not described how to use. For example, from documentation I don't know how to use ErrnoException. Does it have field for error code copied from errno, or should I use errno directly when I meet this exception? What message does ErrnoException provide? It's from stderror function or some dependent on caller? Plenty of questions arise when you need to know how do class or function work, and you often need to browse source code to find out what happens. But ideally documentation must be full, so user does not have to look into sources.
I agree.
There is also sensible lack of examples. Look at std.encoding. Well, actually I'm sure that the whole module needs to be rewritten, I don't see any benefits of "templated" approach to work with encoding. Other thing is "auto" as returned type. It's very handy in code, but I think library documentation should mark returned types more explicitly. So there is many work on Phobos documentation to make it better.
Ddoc needs to resolve "auto" to the actual type.
Also there are some deprecated modules needed for replacement, for example, std.stream and std.socketstream (but I'm not sure why). I believe streams are important to ease programming, but they need really good interface and implementation (flexible and extensible), maybe you have some ideas on it.
I think they need to be able to work with ranges. -- /Jacob Carlborg
