Worst Phobos documentation evar!

[Kiith-Sa via Digitalmars-d]

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