Worst Phobos documentation evar!

[Walter Bright via Digitalmars-d]

On 12/31/2014 3:03 PM, Dicebot wrote:
> One of the very first lines:
>
>      $(TABLE2 Kinds of Arrays,
>          $(THEAD Syntax, Description)
>          $(TROW $(ARGS $(I type)*), $(ARGS $(RELATIVE_LINK2 pointers, Pointers
> to data)))
>          $(TROW $(ARGS $(I type)[$(I integer)]), $(ARGS $(RELATIVE_LINK2
> static-arrays, Static arrays)))
>          $(TROW $(ARGS $(I type)[]),  $(ARGS $(RELATIVE_LINK2 dynamic-arrays,
> Dynamic arrays)))
>          $(TROW $(ARGS $(I type)[$(I type)]), $(ARGS $(DDLINK hash-map,
> Associative Arrays, Associative arrays)))
>      )
>
> I had no idea of what it is and how it will look like after doc generation until
> started checking each macro one by one. Similar stuff in md:
>
>      |       Kinds of Arrays    |
>      |--------------------------|
>      | Syntax         | Description |
>      |------------------------------|
>      |`type*`         | [Pointers to data](/arrays.html#pointers)  |
>      |`type[integer]` | [Static arrays](/arrays.html#static-arrays) |
>
>      // etc.

It's quite unfair to not bother with whitespace formatting in one but not the 
other. It's like the "before" and "after" advertisements for cosmetics where the 
"before" has uncombed hair, poor lighting, is frowning, didn't brush their 
teeth, frumpy clothes, etc., and you know what they did with the "after" picture.

Furthermore, the person who wrote the Ddoc macros not only did not bother to 
format, he also used unnecessary markup - the $(ARGS) is redundant.

Making some effort myself:

$(TABLE2 Kinds of Arrays,
   $(THEAD Syntax            , Description                           )
   $(TROW  $(I type*)        , $(LINK2 #pointers, Pointers to data)  )
   $(TROW  $(I type[integer]), $(LINK2 #static-arrays, Static arrays))
)

versus:

  |Kinds of Arrays|
  |---|
  |Syntax|Description|
  |-|
  |`type*`|[Pointers to data](/arrays.html#pointers)|
  |`type[integer]`|[Static arrays](/arrays.html#static-arrays)|