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.

Reply via email to