www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Question about the validness of code examples in the docs

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? 
Jun 24 2010