colour lib needs reviewers

[Manu via Digitalmars-d]

On 15 September 2016 at 13:49, Andrei Alexandrescu via Digitalmars-d
<digitalmars-d at puremagic.com> 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.

That's absolutely what I'm saying, but not only that, given that I'm
being forced into it now, I'm actively not enjoying it.
I understand it's a macro system, and I'm saying that's the problem as
I perceive it :)

I clearly recall when I learned doxygen. I generally liked it, and I
was motivated to populate my code with docs.
Perhaps there's an obvious counter-pressure in this case since I
already know doxygen, but I think that's insignificant compared to the
fact that I just don't like ddoc.
This macro system is not what I would have done, and it's just not
compelling. I don't want documentation-realted macro definitions in my
code. I also hate the paren spam.


>> 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?

I think of those examples, doxygen is objectively the least annoying
syntax! It's 2 bytes, and doesn't introduce delimiters or parens of
any kind.

Sure, that's definitely an influence, I hate paren spam, but it's not
all. If in practise I was able to make my docs be how I want as easily
as I was able to the first time I encountered doxygen, I wouldn't be
bothered. But I've had a number of contacts with ddoc now, and it's
just not intuitive how to make my docs how I want, whereas with
doxygen, I was walking within minutes, seconds even.

I think I have a sense of uneasy-ness that comes from my intuition
that macros are macros, and I don't know which ones are 'special', or
which are just macros.
Ie, some macros are obviously not actually macros, but keywords in disguise.
Doxygen says things like "\a word" (style this as an argument), ddoc
seems to be $(I word) (italic this), which says nothing about the
semantic meaning of the thing allowing styling to be deferred.
I refer to this page: https://dlang.org/spec/ddoc.html
There's nothing there that says how to style a template argument for
instance, it's all 'italic, big, small, bold' etc, and skimming other
ddoc code, I see people using raw styling like $(I ..) (as you just
demonstrated above).
At face value, it feels clumsy and poorly defined. I'm sure I'm
incorrect, but I just didn't have this same first-impression with
doxygen, or C#'s doco standard (they're the only 2 others I've used
before).

The only reference I've ever looked at for doxygen is this page:
https://www.stack.nl/~dimitri/doxygen/manual/commands.html
I never read another line from their manuals, everything else emerged
via osmosis, and I think osmosis is the correct way a programmer
should learn this stuff, which means it needs to be as obvious and
intuitive as possible.


> 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.

Do you feel that doxygen is not a ubiquitous standard? It's been
around for like 20 years.
I can't think of any non-doxygen docs I interact with regularly other
than Microsoft docs... Maybe this is just a C/C++ ecosystem thing?


> 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.)

Well, I think the core of my uneasy-ness is that the macros have no
clear semantic meaning.
Obviously I can design my own set of macros that express my semantic
meaning... to hell with standards! ;)
Your prior post said "here's a bunch of macros I never leave home
without", that's exactly the problem as I see it.
I don't want too see ddoc macro definition blocks appearing at random
locations in my source code.

And I'll also remind you of my past criticism that my solution to
porting C code to D, is to block delete the doxygen comment blocks
rather than bothering to port them to D. If I had a reason to say what
you said above "if we replace the macro syntax with one closer to
doxygen...", this is that reason, but it's the fact that they're
macros rather than keywords that makes me upset, so replacing the
macros with a different syntax probably won't make me feel less
uneasy.

Perhaps my uneasy-ness would subside if the list of 'builtins'
(https://dlang.org/spec/ddoc.html) was more comprehensive (comparable
to doxygen commands), and I never saw a ddoc macro definition in code
anywhere. My gripe with the syntax would probably have passed without
comment if that were the case and I would have just gotten used to it.

And don't get me wrong, I think it's absolutely fantastic that D has a
built-in documentation system. I just don't really like it.