Hi,
I'm doing a review of the language reference documentation.
What I've noticed in a lot of the example code is that it is not syntactically
correct. Sometimes, this is wanted behavior. For example, take this Array
Length code example:
int[4] foo;
int[] bar = foo;
int* p = &foo[0];
// These expressions are equivalent:
bar[]
bar[0 .. 4]
bar[0 .. $]
bar[0 .. bar.length]
p[0 .. $] // '$' is not defined, since p is not an array
bar[0]+$ // '$' is not defined, out of scope of [ ]
bar[$-1] // retrieves last element of the array
The goal of this example is to show that the dollar symbol is not available for
pointers, or when it is outside the scope of the array. So the example should
not compile.
The above code won't compile, which was expected, but it won't compile for a
number of different reasons:
(1) Statement terminators are missing,
(2) The expressions have no effect, "array[2];" doesn't mean anything
to the compiler and it will complain about it, and finally
(3) $ is undefined in those two expressions, just like noted in the comments
This is a trivial example, but other examples have even worse broken syntax. In
one code example taken from the docs, I got this little monster of an error
message:
foreach_test.d(38): Error: function
object.AssociativeArray!(const(char)[],double).AssociativeArray.opApply
(scope int delegate(ref const(char)[], ref double) dg) is not callable
using argument types (int delegate(ref double __applyArg0,
ref char[] __applyArg1))
foreach_test.d(38): Error: cannot implicitly convert expression
(__foreachbody524) of type int delegate(ref double __applyArg0,
ref char[] __applyArg1) to int delegate(ref double)
With all of that said, the above Array Length example would then possibly look
like this instead:
int[4] foo;
int[] bar = foo;
int* p = &foo[0];
// These expressions are equivalent:
writeln( bar[] );
writeln( bar[0 .. 4] );
writeln( bar[0 .. $] );
writeln( bar[0 .. bar.length] );
writeln( p[0 .. $] ); // '$' is not defined, since p is not
an array
writeln( bar[0]+$ ); // '$' is not defined, out of scope of [ ]
writeln( bar[$-1] ); // retrieves last element of the array
Now the compiler would only complain about the undefined dollar sign, which is
what the code example was trying to show in the first place.
My question to Walter/Andrei and the community is, would you rather see
compilable examples which show you the same errors (if any) as noted in the
code comments, or leave the code examples as they were?
