Worst Phobos documentation evar!

[Kiith-Sa via Digitalmars-d]

On Monday, 29 December 2014 at 19:47:50 UTC, Walter Bright wrote:
> On 12/29/2014 3:19 AM, Jacob Carlborg wrote:
>> On 2014-12-29 06:39, Walter Bright wrote:
>>
>>> Having used both Ddoc and Markdown, I seriously disagree with
>>> this. Take
>>> a look at the markdown source for DIP69. It's horrific.
>>
>> Do you mean on the wiki? The wiki doesn't use Markdown. At
>> least not anyone I've
>> seen.
>
> It uses something pretty similar. They all kinda mush together
> in my mind :-(

It's NOT SIMILAR at all. It's a completely different language. 
Also as mentioned above, DDoc macros are extremely ugly and hard 
to read (and to make sense of, with their lisp-ness).

Not to mention, *almost everyone* coding today knows Markdown and 
can immediately begin contributing to the docs, without looking 
up DDoc documentation or a *freaking macro file in one of D's 
repositories*. Only a subset of D devs know DDoc macros, and a 
very small minority of those know DDoc macros used by Phobos.

This is ugly, it is the *very definition* of ugly. (how the heck 
am I even supposed to read that?):


DDoc:

$(OL $(LI If $(D line) has type $(D string), $(D
wstring), or $(D dstring), a new string of the respective type
is allocated every read.) $(LI If $(D line) has type $(D
char[]), $(D wchar[]), $(D dchar[]), the line's content
will be reused (overwritten) across reads.) $(LI If $(D line)
has type $(D immutable(ubyte)[]), the behavior is similar to
case (1), except that no UTF checking is attempted upon input.) 
$(LI
If $(D line) has type $(D ubyte[]), the behavior is
similar to case (2), except that no UTF checking is attempted upon
input.))


This is *much less ugly*:

Markdown:

1. If `line` has type `string`, `wstring`, or `dstring`, a new
    string of the respective type is allocated every read.
2. If `line` has type `char[]`, `wchar[]`, `dchar[]`, the line's
    content will be reused (overwritten) across reads.
3. If `line` has type `immutable(ubyte)[]`, the behavior is
    similar to case (1), except that no UTF checking is attempted
    upon input.
4. If `line` has type `ubyte[]`, the behavior is similar to
    case (2), except that no UTF checking is attempted upon input.



And my favorite, tables in DDoc. First 3 lines for brevity:


DDoc:

$(BOOKTABLE Cheat Sheet,
$(TR $(TH Function Name) $(TH Description)
)
$(LEADINGROW Searching
)
$(TR $(TDNW $(LREF all)) $(TD $(D all!"a > 0"([1, 2, 3, 4])) 
returns $(D true) because all elements are positive)
)
$(TR $(TDNW $(LREF any)) $(TD $(D any!"a > 0"([1, 2, -3, -4])) 
returns $(D true) because at least one element is positive)
)

...


Markdown (assuming some kind of automatic crossreferencing, which 
*needs* to
be in any decent documentation generator, and DDox, which renders 
your
"preview new" documentation, already does it)

| Function Name | Description                                     
  |
| ------------- 
|------------------------------------------------- |
| #all          | `all!"a > 0"([1, 2, 3, 4])` returns `true` ...  
  |
| #any          | `any!"a > 0"([1, 2, -3, -4])` returns `true` 
... |

(shortened to fit mail, but you should be able to get the point)


If you don't want so many pipes / aligning work, this works too:

Function Name | Description
- | -
#all | `all!"a > 0"([1, 2, 3, 4])` returns `true` ...
#any | `any!"a > 0"([1, 2, -3, -4])` returns `true` ...


And yes, the above is limited, it can't do everything DDoc can 
do.  Macros are
useful when you need something way out of the ordinary. But using 
them for
things like tables or lists or 5 different macros for links 
because you don't
think cross-referencing is important is insane.


I'd be happy if I could use *something that's not DDoc macros* 
99% of the time.
But if I want my docs to be anything better than bare text with 
Params:,
Returns: and Examples:, I have to write that kind of gibberish 
(actually, not
anymore, as I said I'm working on DDoc + markdown).