Worst Phobos documentation evar!

[Manu via Digitalmars-d]

On 31 December 2014 at 09:39, Andrei Alexandrescu via Digitalmars-d
<digitalmars-d at puremagic.com> wrote:
>
> My question is how we can break this pattern? What steps can the D
> leadership take to convince folks like you to actually add, even with the
> simplest things?

I'll answer this, I suspect I'm one of the people you're talking about.
Past what I already do, which I don't think is insignificant; I have
hosted lectures to my local community, extensively promoted and
advocated in my community and industry, report lots of bugs, and try
and maintain a relevant voice for my industry in discussions - which
is very time consuming these days! ... But I obviously don't commit
code.

There are practical reasons for this:
 - I have very little free time.
 - I don't want to be a contributor, I have so much other work that I
want to get done, and I don't want to put that aside.

Despite that, I have made attempts at contributing code on multiple
occasions. They have gone like this:
 - Clone repo, doesn't build in Visual Studio... do something else instead.
 - Work on new phobos module, blocked by some other thing, can't
continue... (std.simd is blocked by __forceinline)
 - Unit tests are really hard to write. (std.simd is hard to unittest,
more time consuming than writing the module itself)
 - Documentation is hard to write. (std.simd has so many functions,
it's a daunting task!)

So I made a solid effort to contribute code, but those were the
frictions that prevented me from getting it over the line (one remains
a blocker).

And further from that, and somewhat more fundamentally, when it comes
to the sort of contribution that I'd *really* actually want to make,
I'm convinced that my changes would never be pulled.
My vision for the language is almost perpetually at odds with yours.
Unless I can win an argument with you (even once!), then nothing could
be more demotivating to me than realising that no matter what I do, my
work would be rejected on principle.

You devastated the substantial amount of motivation I had the day that
you had a spaz about final-by-default, and insisted that the code be
reverted (after was debated for months, unanimously agreed, approved,
written, LGTM, and merged).
I am still trying to recover from that, but that really killed it for
me. That was a very hard fought battle, I won over everyone except
Dejan (who was indifferent), and you. You casually played your veto,
and devastated my enthusiasm. I feel eternally frustrated and somewhat
passive-aggressive since that incident, and I know that's not doing me
any favours. But it solidified my suspicion that I have nothing to add
on that front.

I tried to contribute to VisualD at some times, but that's kinda hard.
I mean absolutely no disrespect to Rainer, who I think is one of the
most important guys around here, but he wrote it in D (which I can
understand - eating your own dogfood and all), and visual studio
plugins are written in C#. It's really hard to get on board with that
project's code. He's obviously struggled through the complicated
integration (massive binding effort!), and he's comfortable with it
now. I certainly wouldn't want to spawn a competing effort.
And aside from that, I've said on countless occasions that I think the
biggest blocker to really quality IDE integration at this point, is
that there's still no libdmd. There are multiple duplicate projects
attempting to parse D code for IDE integration, but I find it hard to
imagine they'll ever really nail the job perfectly. The DMD front-end
is the best piece of code for understanding D that there is, we need
it's parser available to tooling.
It's also a bit sad that some contributors are spending heaps of time
on that effort, which really just seems like a distraction from what
they actually set out to do, which was produce quality IDE
integration.

Considering the documentation problem, I feel like I can get amongst
that, but I also feel the same as others have expressed when I go to
make a move on it; that ddoc comment blocks are something of an
unreadable wall of text. It just 'feels hard', and nobody loves
documenting. It might be okay for those already invested, but to
newbies, it's appears somewhat repelling.
If it were my show, I would never have accepted a pull where a single
function or symbol wasn't comprehensively documented by the author.
I've experienced the documentation deficit commercially for decades;
the only good solution is to enforce that the author documents their
code to standards at the time of writing, otherwise it will never
happen. Is that standard detailed anywhere?


I feel a bit stuck recently, I am sufficiently married to D now, I use
it for everything. When I started I was optimistic that the problems I
had would be resolved in good time, but most of the big
(controversial) issues I had since day one haven't even budged in the
last 5-6 years. There is activity on the GC/@nogc front, which is
excellent. RC, scope, and ref are remaining, fixing virtual was
denied, and that's my entire list!
I started full-time C/C++ work again recently, and it's torture! I'm
having real trouble enjoying my work when I am eternally frustrated by
language bullshit, but at the same time, I've it is evident that D's
tooling is not sufficient for use professionally in my industry yet.

So, sadly, my motivation is at an all time low. I am watching these
current debates on issues that I've had _very_ significant investment
in for years now, and I fear they're going to go in a direction that I
can't get behind. I can't imagine what half a decade of wasted energy
is going to feel like, so contrary to your request from the other
thread (to be more restrained on debate), I'm finding myself somewhat
more forceful on these topics... what else can I do? Sit back and
watch it drift away?

So I guess, in summary, I feel that nothing I can do will particularly
influence direction. How can I be a contributor in any useful way past
what I already do... which I do still feel is genuinely significant,
despite being somewhat auxiliary.

</walloftext>