Worst Phobos documentation evar!

[Jacob Carlborg via Digitalmars-d]

On 2014-12-28 16:57, 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.
>
> 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've never liked that. I usual write my documentation in Yardoc [1]. 
It's quite similar to JavaDoc, with special tags like @return and 
@param. It's a lot more expressive, like automatically creates links 
(like you're suggesting below), supports adding types to parameters and 
return values. Yardoc is also used for all (most) gems on rubygems.org.

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

Agree.

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

I completely agree. I've complained about this several times. Also, if I 
recall correctly, XREF only works with one package, not with nested 
packages.

[1] http://yardoc.org/

-- 
/Jacob Carlborg