Worst Phobos documentation evar!

[uri via Digitalmars-d]

On Sunday, 28 December 2014 at 15:57:39 UTC, Ary Borenszweig 
wrote:
>
> 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.

-1

Most of the time I know what the function does but I need the 
docs for the parameters and types.

>
> 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).

Again, I don't want to wade through a wall of text just to get 
the parameter types or what a function returns. The signature 
itself is too noise IMO so explicit Return & Param sections are 
preferable IMO.


I'd also like to see TemplateParms: or TemplateTraits:, as others 
have already mentioned.

>
> 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).

DDoc is not hard to read or write so Markdown would be wasted 
effort. If DDoc generated Markdown that might be useful for the 
WIKI.

>
> 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).

+1 I agree links to functions would be much simpler with a #tag.

Cheers,
uri