Worst Phobos documentation evar!

[Xinok via Digitalmars-d]

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.