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.