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
