Worst Phobos documentation evar!

[Kiith-Sa via Digitalmars-d]

On Sunday, 28 December 2014 at 16:44:05 UTC, Kiith-Sa wrote:
> 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?)

argh, formatting, the heading2 thing should be:

heading2
--------