Example within documentations of D seriously need some improvement.

[Matthew Ong]

On 5/27/2011 8:13 PM, Andrej Mitrovic wrote:

 > that just show the syntax of the language, I think foobar is ok.
I totally agree, I wrote that I think. However, the problem are clearly
seen here at least:

http://www.digitalmars.com/d/2.0/operatoroverloading.html # people done 
C++ can understand others may not.
http://www.digitalmars.com/d/2.0/template.html
http://www.digitalmars.com/d/2.0/template-mixin.html
http://www.digitalmars.com/d/2.0/traits.html
http://www.digitalmars.com/d/2.0/statement.html#ScopeGuardStatement
What is that??

There are more such places, please ask someone new around you to feed back.

 > I'm not sure how Vehicles or Bank Account is going to help describe
 > access modifiers. There's no connection, and will end up confusing the
 > reader. Foo and Bar are used when the focus is not on the semantics
 > but on the syntax of the language.

 >end up confusing
Please use nonconfusing common example code that most people would have 
read about in most OOP concept book. Code should speak for itself to 
reflect the purpose of the syntax along with some commonly used 
semantics with the library or day to day coding.

 >Foo and Bar are used when the focus is not on the semantics but on the 
 >syntax of the language.
Yes, I can see what you are trying to do. Syntax without practical 
semantics are meaning less and some practical example does not give
a solid and clear understanding of what that syntax is for.

At a single glance and read, please tell me someone new will understand 
what template mixin, traits and scrope explained?

It should show what is that for, how is that better, do and do not, 
warning, conventions and others.Fundamental of linguistic design.

Hope that clear the doubt that D documentation approach is Not 
self-explaining to the reader even with very few statement outside the 
sample or on the sample code itself.

It is NOT JUST those pages listed here.

-- 
Matthew Ong
email: ongbp at yahoo.com