Worst Phobos documentation evar!
Kiith-Sa via Digitalmars-d
digitalmars-d at puremagic.com
Sun Dec 28 08:45:26 PST 2014
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
--------
More information about the Digitalmars-d
mailing list