Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

On Wednesday, 6 January 2016 at 10:25:50 UTC, Martin Nowak wrote:
> We already have a nice and powerful documentation generator 
> called ddox.

You say that like I've never hard of it before, when I've spent 
quite a few words over the last ten days writing up my critiques 
of it, including both bugs and questioning its fundamental 
approach.

I guess I'll write more about it. I really wish you guys would 
actually read the arguments you're replying to though before 
posting. This is very frustrating and contrary to popular belief, 
I'm not a saint with infinite patience.

> https://github.com/rejectedsoftware/ddox
> It also contains an experimental libdparse based input (rather 
> than relying on dmd's json ouput).

I confess I didn't actually know it had that (it has zero 
mention... anywhere outside the source)... though the fact that 
it is there actually strengthens my position! Look at the ddox 
issues list, marked external. Those are from dmd... but they 
aren't all bugs. The JSON isn't just for docs, and when there's a 
trade off between doc and whatever else people use the json for, 
the doc side often loses.

e.g.:
https://github.com/rejectedsoftware/ddox/issues/19

Apparently, the ddox team agrees with me that being wed to dmd is 
a flawed approach.


Though, looking at its source, it doesn't actually use libdparse 
for much beyond the basics - just getting enough to feed into the 
existing core, which reflects its preference for the inferior 
json, and it appears to be stalled there. It is still limited by 
its initial decision of going down the dmd route.

> It is flexible enough to be templated/styled very differently

That's trivial. Even the worst html file is flexible enough to be 
templated/styled very differently because that's part of html's 
core nature.

> the project is actively maintained

With about 1/3 of its github bugs still open, including about 
half its open bugs more than one year old. About half its D 
bugzilla bugs are still open, including ones over 2 1/2 years old.

I know projects get bugs open when they are used, but ddox is a 
one-person project and that one person doesn't seem terribly 
active in it.

https://github.com/rejectedsoftware/ddox/graphs/contributors


Looking at the bug list, lol:
https://issues.dlang.org/show_bug.cgi?id=14608

It was open for six months without so much as a comment. The 
thing Andrei is asking for and Sonke agrees is a good model... is 
exactly the way I did mine the first time.

http://dpldocs.info/experimental-docs-2/std.algorithm.searching.OpenRight.html



And yes, yes, I'm sure if I spent 60 hours on ddox over this 
Christmas instead of on my new system, some of those bugs would 
be closed. But I betcha I would have hit some annoying wall and 
instead spent the time on my paying job or something (I do have a 
big tax bill looming and probably should be doing paying work!), 
so that's all hypothetical.

And when I did open a pull request, it'd probably sit there for 
over two months without comment like the other ones that are open 
right now. I'd have to fork the site anyway to get any changes 
live!

> ddox compatible tools can easily be integrated with dub, and 
> whatever you want to change for template constraints should be 
> easy to achieve.

The template constraint formatting is just the beginning.