Worst Phobos documentation evar!

[bachmeier via Digitalmars-d]

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.