Worst Phobos documentation evar!

[Ary Borenszweig via Digitalmars-d]

On 12/27/14 10:00 PM, 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.

After programming in Ruby for a long time (and I think in Python it's 
the same) I came to the conclusion that all the sections (Return, 
Params, Example) just make writing the documentation a harder task. For 
example:

~~~
/*
  * Returns a lowered-case version of a string.
  *
  * Params:
  *   - x: the string to be lowered case
  * Return: the string in lower cases
  */
string lowercase(string x)
~~~

It's kind of redundant. True, there might be something more to say about 
the parameters or the return value, but if you are reading the 
documentation then you might as well read a whole paragraph explaining 
everything about it.

For example, this is the documentation for the String#downcase method in 
Ruby:

~~~
def downcase(str)

Returns a copy of `str` with all uppercase letters replaced with their 
lowercase counterparts. The operation is locale insensitive—only 
characters “A” to “Z” are affected. Note: case replacement is effective 
only in ASCII region.

     "hEllO".downcase   #=> "hello"
~~~

Note how the documentation directly mentions the parameters. There's 
also an example snippet there, that is denoted by indenting code 
(similar to Markdown).

I think it would be much better to use Markdown for the documentation, 
as it is so popular and easy to read (although not that easy to parse).

Then it would be awesome if the documentation could be smarter, 
providing semi-automatic links. For example writing "#string.join" would 
create a link to that function in that module (the $(XREF ...) is very 
noisy and verbose).