On Friday, 10 January 2014 at 14:02:16 UTC, Jacob Carlborg wrote:
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.
Unless it's a voldemort type.
