Worst Phobos documentation evar!

ketmar via Digitalmars-d digitalmars-d at puremagic.com
Wed Dec 31 13:23:43 PST 2014


On Wed, 31 Dec 2014 12:40:20 -0800
Walter Bright via Digitalmars-d <digitalmars-d at puremagic.com> wrote:

> On 12/31/2014 7:13 AM, Jacob Carlborg wrote:
> > I don't agree, I feel the opposite. Markdown is superior to Ddoc in writing
> > documentation for code. Not web sites, not books, but documentation for code.
> 
> Documentation for code winds up on a web site.

finally, i got your point. D is *your* *personal* *project*. not more,
not less. it something is handy for you, it will be in D, and it
doesn't matter how much other people arguing about changing it. if
something is of no use for you, it would be a miracle to see it in D,
even when the code is ready and almost anyone who cares about the thing
anough wrote "yes, do it!" and i'm not talking about Ddoc here.

and about Ddoc/markdown issue: the quoted sentense says it all. you
want Ddoc to be able to produce websites. and you don't care if some
other people think that Ddoc was invented for documenting the source
code. you know, documenting sources implies easy reading by human
without preprocesing. and easy human-readable format is easy to write.
but yes, it can't create a cool website for you. nor it is good for DTP.

you keep inventing artificial samples to show that one still has to use
escaping in markdown. you know, looking at Ddoc, which consists mostly
of visual noise, i can tell you that markdown is god-given immortal
purity.

yet i got the idea: Ddoc is for websites, not for API documentation. it
happens to understand some D, but the primary goal is to create
website. ok. we just misunderstood why Ddoc is here.

i appreciate all your hard work on D (and on C/C++ compilers too, which
i was used from time to time). but do you really want D to be a widely
used language? seems that you are thinking about some "future users",
who will surely need to write a complex documents right in the D source
code, so Ddoc must resemble DTP languages. that they ("future
users") will write alot of code and so we can't break that unwritten
code by changing the language now. and so on.

what you seem to miss here is that it's the current D users who
spreading a word. make D better for current passionate users, and you
may get those "future users" in the future. make D great, but
frustrating for current passionate users, and you will get no "future
users" at all, 'cause there will be nobody to spread a word about D.

i, for myself, can't see why i have to endure annoyance in the name of
"future users". those "future users" did nothing for me, except making
D frustrating. the thing is that "future users" will have to take what
we giving 'em, not we have to take something that *might* please those
"future users".

do you think that vibe.d is a valuable project? Sönke wants property
enforcement syntax, for example. just ask him! and patch for that
syntax is already here. that patch works, my DMD build using it. yet
Sönke will not come here to argue for this feature for month (or
years?), he is busy developing vibe.d (and other things). Sönke is a
real user with a real project. he can live without property
enforcement, but... besides, enforcing property syntax will solve the
bug with delegate properties, where they need `()()` to really call the
delegate. and we have dfix which can be extended to automatically fix
user code.

and what about tuple syntax? two years passed since PR was submitted.
isn't it enough to stop thinking about how accepting that PR will close
the opportunity to invent better syntax in the future and just accept
it? two years of stagnation is enough to see that this feature is not
at the top of priority list and you and Andrei will *always* have more
important tasks to do. so just merge it and forget! (yes, i know that
it can't be merged right now without rebasing; seems that we simply lost
it)


sorry. i hate new years.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 181 bytes
Desc: not available
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20141231/d5dba637/attachment.sig>


More information about the Digitalmars-d mailing list