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
