On Sunday, 28 December 2014 at 02:55:39 UTC, Xinok wrote:
On Sunday, 28 December 2014 at 01:00:49 UTC, Walter Bright
wrote:
This is so bad there isn't even a direct link to it, it hides
in shame. Just go here:
http://dlang.org/phobos/std_encoding.html#.transcode
and scroll up one entry. Here it is:
size_t encode(Tgt, Src, R)(in Src[] s, R range);
Encodes c in units of type E and writes the result to the
output range R.
Returns the number of Es written.
Let me enumerate the awesomeness of its awfulness:
1. No 'Return:' block, though it obviously returns a value.
2. No 'Params:' block, though it obviously has parameters.
3. No 'Example:' block
4. No comparison with other 'encode' functions in the same
module.
5. No description of what 'Tgt' is.
6. No description of what 'Src' is.
7. No clue where the variable 'c' comes from.
8. No clue where the type 'E' comes from.
9. 'R' is a type, not an instance.
10. I suspect it has something to do with UTF encodings, but
there is no clue.
There's simply no way to figure out what is going on here
without reading the source code.
Anyone want to take this on? There's a lot of stuff like this
in Phobos. It's too much for one person to tackle, but if each
of us just pick a function here and there, we can crowdsource
and improve things greatly.
Some ones I've done, as examples of easy improvements:
https://github.com/D-Programming-Language/phobos/pull/2805
https://github.com/D-Programming-Language/phobos/pull/2812
https://github.com/D-Programming-Language/phobos/pull/2813
https://github.com/D-Programming-Language/phobos/pull/2814
I'd like to contribute to the documentation (more within my
skill level anyways), but I'd like to follow some solid
guidelines if I'm to do so. If we don't have something like it
already, perhaps we could create a page on the wiki with some
tips and conventions for writing documentation for Phobos (and
if we do, give me a link!). Then of course, we can incorporate
some good and bad examples which you've provided for us already.
That's a good idea. I propose rule #1: Under no circumstances
will auto be allowed in any examples. The compiler should even
reject files in which they appear. One of the most frustrating
things is to read documentation with type T (completely
uninformative) followed by an example with auto.