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