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.
