On Thu, Jul 23, 2015 at 04:54:50PM +0000, jmh530 via Digitalmars-d wrote: [...]
> I see that now. It's there, but it's practically a throw-a-way line. I've looked at that page a bunch of times and skipped over it each time. This is a broader problem with D's reference pages.
> 
> Compare
> http://dlang.org/interface.html
> with
> https://doc.rust-lang.org/book/traits.html
> which is better?
> 
> Rust's documentation uses clear examples to show how something should be used and the most important features. By contrast, there are many parts of D's documentation that someone with less-than-expert programming knowledge will find quite difficult to understand.
> 
> For instance, look at http://dlang.org/function.html you have to scroll down for quite a while before you even get to anything useful. Then, what's the first thing that comes up? Something about contracts, return values, bodies, purity. Not "this is what a D function is".
> 
> I'm all for a complete reference of every D feature, but there needs to be some step up in terms of difficulty of the material. Start with the basics, then work up into all the specifics. I'd say at a minimum some of this documentation needs to be broken up into several pages.
> 
> There seem to be a lot of places where I could improve the D documentation.  However, I feel like if I start going crazy with changes I might get some push-back...
[...]

Please bring on the PR's, we need all the help we can get!

As for push-back... as long as each PR is focused on one thing, e.g., improving the prose, or adding a beginner-friendly example to the top of the page, I think it will be acceptable. Just don't put too many changes into one PR (reformat the source, fix whitespace, rewrite 5 disparate paragraphs, etc., you know what I mean).


T

-- 
Notwithstanding the eloquent discontent that you have just respectfully expressed at length against my verbal capabilities, I am afraid that I must unfortunately bring it to your attention that I am, in fact, NOT verbose.

On 2015-07-22 3:35 PM, John Colvin wrote:
> On Wednesday, 22 July 2015 at 21:36:58 UTC, jmh530 wrote:
>> On Wednesday, 22 July 2015 at 20:43:04 UTC, simendsjo wrote:
>>> When "everything" is an expressions, you can write things like
>>>     auto a = if(e) c else d;
>>>
>>> In D you have to write
>>>     type a = invalid_value;
>>>     if(e) a = c;
>>>     else  a = d;
>>>     assert(a != invalid_value);
>>>
>>
>>
>> I prefer this example from one of the various Rust tutorials
>>
>> let foo = if x == 5 {
>>                 "five"
>>           }
>>           else if x == 6 {
>>                 "six"
>>           }
>>           else {
>>                 "neither"
>>           }
>>
>> You're basically using a conditional expression as an rvalue. You can
>> do the same thing with a { } block.
>
> Admittedly nowhere near as clean, but if you can bear to see the
> "return"s, function literals can turn any bunch of code in to an
> expression:
>
> auto foo = { if(x == 5)
>                           return "five";
>                       else if(x == 6)
>                           return "six";
>                       else
>                           return "neither";
>                     }();
>
> or of course there's the perhaps overly terse (brackets optional, i like
> them to visually group the condition with the ? ):
>
> auto foo = (x == 5)? "five"
>                     : (x == 6)? "six"
>                     : "neither";


Shouldn't that be its own function anyway?  If you needed it in one place, you'll probably need it elsewhere.  And, in this case, it can even be marked as pure.

On Wednesday, 22 July 2015 at 21:03:52 UTC, simendsjo wrote:
> On Wednesday, 22 July 2015 at 19:54:05 UTC, Dicebot wrote:
>> Macros are utterly horrible and pretty much unusable outside
>> of advanced library internals.
>
> Not sure what you are referencing here. Macros expand to code. If
> you compare this to string mixins, they are a lot easier for tool
> writers, but a lot less powerful.
>

I've read that someone managed to implement compile time regex using macros in Rust. The author of it noted that D was the only other language he knew of that had pulled that off. The fact that it's expressive enough to pull off one of Phobo's coolest tricks is impressive I think. I don't know enough about it to have my own opinions of how it fairs against D in general. It could very well be that doing stuff like that is far beyond anyone but the most advanced users though I don't think many D users could pull of what Dmitry has done either.

On 7/23/15 12:54 PM, jmh530 wrote:
> There seem to be a lot of places where I could improve the D
> documentation. However, I feel like if I start going crazy with changes
> I might get some push-back...

Focused, specialized, and  clear pull requests are the way to go here. -- Andrei

On Thursday, 23 July 2015 at 16:54:52 UTC, jmh530 wrote:
> This is cool and I wasn't aware that you could do this. I was trying to use std.traits' InterfacesTuple to test that a class had a particular interface.
>

Again, I just found a reference to this behavior in the template section where it talks about Argument Deduction. No idea it was there. There were two things that I thought Rust's traits could do, but D's interfaces couldn't do. Now it seems like D's interfaces could do both of them.

On Thursday, 23 July 2015 at 16:54:52 UTC, jmh530 wrote:
> Rust's documentation uses clear examples to show how something should be used and the most important features. By contrast, there are many parts of D's documentation that someone with less-than-expert programming knowledge will find quite difficult to understand.

Yeah, I agree. Here's what I've been trying to write:

A template for tutorials:

show how to do it

link to features as they are discussed

Feature template:
        What it is
                so like a mixin template is a list of declarations with names
        Core concept in usage
                mixin template example, basic use
                use with templates
                use with a name to mix in overloads
        Where it is used in tutorials and other places IRL




That's the skeleton outline for how I want to do docs. The "what it is" we kinda have now, though it could often be clearer, but we don't have the nice examples (well, outside of things like my book) and we certainly don't have the top-level how to do X in the whole ecosystem, and the interlinking to learn more.




Of course, this goes slowly because answering questions is kinda fast, but making it archivable and presentable in depth is a slow process and I just have a hundred other things to do too :(

speaking of which, work meeting in 30 mins, and my presentation isn't ready yet, i shouldn't be on this forum at all right now!



> I'm all for a complete reference of every D feature, but there needs to be some step up in terms of difficulty of the material. Start with the basics, then work up into all the specifics. I'd say at a minimum some of this documentation needs to be broken up into several pages.

That would be good. I also think a top-level "the boss whats you to do X and needs it by end of day, follow these steps to learn how and read these links to dive deeper" would be super useful. They should feed into each other.



> However, I also find it a bit confusing. I don't understand precisely what it means when the interface is on the left.


You always create objects, but you can work with interfaces. Ideally, in OOP theory, your functions always work with just interfaces and they don't care what specific class was constructed in the user code. This makes those functions most reusable in the paradigm.

So for the local variable, using an interface doesn't make as much sense, but it is common to write:

void doSomething(MyInterface i) { /* work with i */ }

void main() {
     Foo bar = new Foo();
     doSomething(bar); // bar becomes a MyInterface for this call
}

which would work the same way. Objects will implicitly convert to their interfaces, so you can pass them around to those generic functions.

D also has templates which do something similar at first glace, but work on an entirely different principal...

For the interface/class thing, you can read about it in Java tutorials or documentation. D's system is very similar to Java's so if you understand that foundation a lot more of it will make sense.

Then the next level is the final things and the templates and how they interact which I'm touching the surface on here.

> cases. Then, if you change Foo to not be final and Bar to not override and run it, it will call "foo from bar" regardless of whether you do
> Foo bar = new Bar();
> or
> Bar bar = new Bar();

yeah, if it is non-final, the child implementation gets called. This allows you to substitute a derived class for the base class or interface while getting new behavior.

On Thursday, 23 July 2015 at 17:34:45 UTC, Adam D. Ruppe wrote:
>
> Feature template:
>         What it is
>                 so like a mixin template is a list of declarations with names
>         Core concept in usage
>                 mixin template example, basic use
>                 use with templates
>                 use with a name to mix in overloads
>         Where it is used in tutorials and other places IRL
>
>
>
>
> That's the skeleton outline for how I want to do docs. The "what it is" we kinda have now, though it could often be clearer, but we don't have the nice examples (well, outside of things like my book) and we certainly don't have the top-level how to do X in the whole ecosystem, and the interlinking to learn more.
>

Definitely sounds interesting.

>
> That would be good. I also think a top-level "the boss whats you to do X and needs it by end of day, follow these steps to learn how and read these links to dive deeper" would be super useful. They should feed into each other.
>

I actually just had your D Cookbook delivered a few days ago. Beyond a few cases of extra semi-colons, one of the things that really stood out were where you took something I would find very complicated, describe the few key steps to accomplish the complicated task, and then follow up with a bunch of code that does those steps. I like that teaching method.

On 07/23/2015 06:28 PM, Andrei Alexandrescu wrote:
> On 7/23/15 10:49 AM, ixid wrote:
>> On Thursday, 23 July 2015 at 13:33:43 UTC, Adam D. Ruppe wrote:
>>> On Wednesday, 22 July 2015 at 21:04:57 UTC, simendsjo wrote:
>>>> :) The example was written to save space. I recon you understand what
>>>> I mean.
>>>
>>> Yeah, but the if/else is one of the most useful examples of it, and is
>>> covered by ?:, so the whole thing becomes less compelling then.
>>>
>>> The other places where I've used it in languages that support it are
>>> little blocks crammed into a line and sometimes exception grabbing...
>>> but still, the value isn't that great.
>>
>> If we had a clean sheet wouldn't it be better to have if return a value
>> and ditch ternary?
>
> Possibly, but then you'd need to have while return a value. -- Andrei

https://en.wikipedia.org/wiki/Unit_type

On Thursday, 23 July 2015 at 17:43:49 UTC, jmh530 wrote:
> I actually just had your D Cookbook delivered a few days ago. Beyond a few cases of extra semi-colons

That gets better! I didn't realize how the editing process worked when I turned in chapter one so it is embarrassingly bad in places, absolutely horrible start, but I figured it out after that so the code will get a lot prettier.

> one of the things that really stood out were where you took something I would find very complicated, describe the few key steps to accomplish the complicated task, and then follow up with a bunch of code that does those steps. I like that teaching method.

I think a strong foundation - knowing the basics really well - is the key to being a good programmer. Most hard things can be broken down into a combination of a few basic things. Andrei's "design by introspection" hits this same principle: looking at pieces and just working with them, knowing what they can and can't do one part at a time, is easier than trying to name and master all the various combinations of them.

So that was what I wanted to do in my book: start with something bigger, but focus on the building blocks with the hope that you'll be able to reassemble them into something new for yourself in the end.



A concrete example, consider std.typecons.Typedef. I think that is totally useless because if you understand what it does, it is trivial to do your own with various customizations specific to you (like allowing or disallowing implicit conversions, disabling individual operators, etc).

Or to just do the basics is easy if you know how it is built (it is really just a plain struct!).


Whereas if you don't understand the building blocks, you're lost when you need to customize it somehow (and there's too many options to reasonably name each of them in Phobos)... and you are also likely to be surprised by bugs when they come up, like with the Typedef cookie parameter.

So knowing structs is IMO far more valuable knowledge than knowing Typedef.


But at the same time, having pre-made kits is helpful too, especially as starting points, so when i get to my tutorial series, I want to get more of that.

On Thursday, 23 July 2015 at 16:46:01 UTC, Laeeth Isharc wrote:
> Dicebot:
>  D has done many things wrong, but there is one right thing that
>> totally outshines it all - it is cost-effective and pragmatical tool for a very wide scope of applications.
>
> would you care to write more on this as a blog post, making it vivid and setting out some examples?  that's my tentative judgement too, and why I am here, but I lean very heavily on my intuition and that's not enough to persuade other people when I don't yet have mastery of the relevant domain knowledge, having returned to programming quite recently.  I am talking to another decent-sized hf that might be open to exploring the use of D, but the more vivid people are able to make the case the better.

AFAIR Don had quite a good summary at DConf 2013 (http://dconf.org/2013/talks/clugston.html) for how it applies to our business. I guess that presentation can still be used as selling point.

I like to put it this way : only very few of Sociomantic developers knew at least something about D before joining the company. It were mostly C++/Java/Whatever developers which learned everything on spot. We haven't even had any special training courses - just giving one book (Learn Tango with D) and few weeks of time to experiment was usually enough to start righting some production code, learning more advanced stuff later on per-need basis from reviewer comments.

Considering growing deficit of skilled programmers in the industry in general being able to kickstart into new language like that is a very big deal for business. C style syntax brings familiarity and being able to write working apps with simple concepts only (even if they are un-idiomatic in "modern D") greatly improves learning curve.

No matter how many effort is put into tooling or documentation, I simply can't see Rust ever being used like that. Well, unless it gets studied commonly as part of computer science BSc and most new devs will be at least faimilar with it. Writing simple number guessing app (like one presented in Rust book) can easily take half an hour for even experienced (but new to Rust) developer - it simply won't compile until you get every single smallest bit _right_. In small to medium business you simply can't afford investments like that.

I see Rust as possible language of choice for a very small (but important) subset of applications of big enough size that maintenance costs are much greater than development costs AND both performance and safety matter. AAA games, life-critical real-time software, software monsters like your next Firefox or Photoshop. That is big enough share of market in terms of money for language to keep being demanded but it is tiny minority of applications in terms of pure project count. It is clearly not your average next project.