Worst Phobos documentation evar!

[Kiith-Sa via Digitalmars-d]

On Monday, 29 December 2014 at 23:56:47 UTC, Walter Bright wrote:
> On 12/29/2014 3:31 PM, Kiith-Sa wrote:
>> because I need macros even for something as common as an 
>> inline code fragment.
>
> Markup, macro, same thing.
>
>
>> Not to mention, if I include the full table lines, not just 
>> ~70 chars this
>> newsgroup will take, the difference in readability is much 
>> more massive.
>
> Not really, because you can create your own custom macros to 
> shorten things up.
>
> I use Ddoc all the time, and I create custom macros ALL THE 
> TIME for semantic shortcuts, prettying things up, saving 
> typing, etc. Any repetitive tasks are candidates for a custom 
> macro.
>
> If you're not using custom macros, and you find Ddoc tedious 
> and repetitive, you're using it wrong.

I cannot use a custom macro to shorten $(D a == b). A 
well-written paragraph will have 20 such $(D XXX), $(B XXX), $(I 
XXX), not to mention $(SOMELINK xxx.com XXX). And there's no way 
to make lists or tables readable: *unless* their contents is 
homogenous, at best I will have rows full of $(XXX ).
etc. is completely unreadable for anyone but people who have 
spent at least a year looking at the mess that is Phobos 
documentation comments.
Javadoc is more readable in sources, as is Doxygen. Python's 
Sphinx is more readable in their sources. 
[Rust](http://doc.rust-lang.org/rustdoc.html) is using markdown 
for their documentation and they don't have any issues either.

Yes, *you* use DDoc all the time. But *you* are also forcing it 
on everyone using the language, and on any average programmer who 
may potentially use D, most of whom don't share your love for 
macros and MANY of whom know much more common formats like 
Markdown. Most people don't write their docs in LaTeX either.

Besides, no-one is proposing to *remove* the macros, the proposal 
it to add syntax for basic cases which frankly can *not* be made 
any less ugly with macros. And yeah, so you will need to escape

I'm writing my *thesis* in ReStructuredText, which is basically 
Markdown on steroids with *way* more special characters than 
Markdown, and I almost never need to escape anything.


Either way, I'm done with this argument, I expect it will take 
many more pissed-off users for this to change.



As for the CSS thing, yes, you need that built in. It doesn't 
have to be amazing but it *has to be usable*.

to be usable, documentation must be as simple to generate as:

   doxygen Doxyfile


That's what a user coming from most different languages expects, 
if they don't get it, it seems *broken* and is extremely 
off-putting. When I was starting with D this almost made me give 
up. Bare HTML files, no cross-referencing, unreadable, no menu. 
No information on the site on how to get a usable documentation 
(not sure how it's now, it's been a few years), and coming from 
Doxygen, writing a bunch of .ddoc files I wasn't even told about 
wasn't what would come to my mind.

The default does not need to look amazing, but there must be 
something usable to start with, without *any* work other than 
having documentation comments in your code. Any other common 
documentation generator will produce something that can at least 
be browsed.