On Thursday, 15 September 2016 at 03:49:55 UTC, Andrei Alexandrescu wrote:
On 9/14/16 9:28 PM, Manu via Digitalmars-d wrote:
Like, I really just don't care enough to try and understand ddoc sufficiently to have a bag of tricks like those you demonstrated above to workaround these issues. It's not a skill I *want* to possess,
rather, in this case, it's a skill I'm being forced into.
You're welcome to call me lazy, I'd suggest I'm being realistic. Perhaps a phobos contributor will be required to work it out (as seems
to be a requirement for me right now), but normal programmers
wouldn't. In 7 years, I've never been motivated to find workarounds to ddoc shortcomings before now, and now, it's only because people are hassling me. There's no intrinsic motivation here... one reason I use
D is because I hate the C preprocessor ;)


I don't see those workarounds to ddoc shortcomings. m4 and all macro systems I know of have similar idioms. It's the nature of macro processing. Are you simply saying you're familiar with other documentation tools and are not motivated to get into another one? That's entirely fair.

If I had to suggest, I'd introduce doxygen style \tags alongside the macros, then when people try and type docs in the way they've been doing for decades, it'll just work, and they can get on with their code. Nobody likes writing documentation, it needs to have the minimum
possible friction or people just won't.

I have difficulty understanding this. I haven't looked at Doxygen in a long time and never really used it, but from what I see at https://www.stack.nl/~dimitri/doxygen/manual/commands.html it seems the \tags you refer to are just a form of macros. The syntax is different, i.e. you'd write \a hello whereas in html you'd write <i>hello</i>, in latex \textit{hello}, in ddoc $(I hello). It's a matter of syntax and though I agree syntax matters (and it would be nice to make ddoc's more configurable), is it right to assume you simply want a syntax you're more familiar with?

How do you mean people "type docs in the way they've been doing for decades"? Are you implying doxygen not only has been around for decades, but it's been some sort of ubiquitous standard? Honest question, I'm definitely not getting that.

doxygen is mostly javadoc compatible and that one is the standard.
(in fact the \ can be replaced by @ every where) and it allows direct html tags. The good thing about doxygen is that it supports also markdown. There are also some niceties like auto brief and autoreferencing (when a symbol is written in a text will be clickable if its body was reachable during generation of the doc).


Does this boil down to - if we replace the macro syntax with one closer to doxygen things will just click? (That may as well be the case.)

Probably. But be reminded of your remark in the SDLang vs. JSON thread from last year: "...this is a strategic error. Please throw s/SDL/DDOC/ away and use a standardized file format. -- Andrei

Reply via email to