On Sunday, 28 December 2014 at 15:57:39 UTC, Ary Borenszweig
wrote:
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).
It depends on the function being documented. For 'downcase', such
blocks are overkill; for more complex functions (and templates!)
they're very helpful
Params: is an excellent place to explain the *requirements* for
the parameters. Even the current doc, which seems to be rewritten
since Walter's post, does not make use of this: there's a
paragraph "The input to this function MUST be validly encoded..."
- this should not be a separate paragraph; it should be mentioned
right in Params: for that parameter. Consistently documenting
requirements/contract for each parameter in the Params: entry for
that parameter makes it easy to find the requirement at glance.
DDoc is powerful, but it is a very nasty case of "hard things are
possible, easy things are hard" (e.g. tables, and very unreadable
in source $(B bold) instead of **bold**, $(D code) instead of
`code`, $(LINK2 ...), etc. .
I'm working on generating documentation with both DDoc and
Markdown in the same source, BTW, but not with the builtin DMD
generator. Most of markdown can be used without conflicts, with
notable exceptions of:
--- // horizontal line (but - - - works)
heading2 // (but ## heading2 works, and '-' can be replaced by
something els)
--------
I think it'd be a good idea to add at least a subset of markdown
to DMD DDoc, which could generate DDoc macros (e.g. **bold**,
*italic*, `inline code` (DDoc already has nice syntax for code
*blocks*), [link](www.link.com), and some table syntax (not in
vanilla markdown, but e.g. GitHub markdown/PanDoc markdown have a
common syntax)
- I may be able to find some time to work on this for DMD DDoc in
summer (not sooner unfortunately, I'd need some time to look
around the code as I never touched it), but would it have a
chance of being merged? (Walter?)
