Reminder: The PR is ready for review:

https://github.com/D-Programming-Language/dlang.org/pull/623

Jonathan has summarized his position in the commments.
What do the rest of you think?
H. S. Teoh, Jakob, Ali, Marc, Dominikus, Chris -
your impression of whether this clears up the confusion would
help round out the feedback.

On Monday, 11 August 2014 at 07:04:42 UTC, Andrew Godfrey wrote:
> Reminder: The PR is ready for review:
>
> https://github.com/D-Programming-Language/dlang.org/pull/623
>
> Jonathan has summarized his position in the commments.
> What do the rest of you think?
> H. S. Teoh, Jakob, Ali, Marc, Dominikus, Chris -
> your impression of whether this clears up the confusion would
> help round out the feedback.

Very good.
Most of the documentation becomes imediately much more intuitive and instructive.
Beside some typos (at one place I saw an uppercase C where a valiable "c" was menat, in another place a variable c is refered but only b was declared), I'm very much in favor of those changes.

On Mon, 11 Aug 2014 07:04:41 +0000
Andrew Godfrey via Digitalmars-d <digitalmars-d@puremagic.com> wrote:

Jonathan is right. what this PR does is changing one (somewhat confusing) terminology to another, even more confusing one.

On Monday, 11 August 2014 at 19:43:26 UTC, ketmar via Digitalmars-d wrote:
> On Mon, 11 Aug 2014 07:04:41 +0000
> Andrew Godfrey via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
>
> Jonathan is right. what this PR does is changing one (somewhat
> confusing) terminology to another, even more confusing one.

Thanks for adding your opinion - it's good to see more support for Jonathan's side.

Don't think I'm being flippant, but I have trouble interpreting such feedback, because D's dynamic array semantics ARE complicated. So if I happened
to succeed in making a clear, accurate description of how it works, I would expect it to take many readers from an inaccurate, overly-simplistic understanding to an accurate (but unfortunately more complex) one.

I have cause to question this - the docs themselves had some important misunderstandings - clear errors.
It's possible that this was cruft and the authors never had those misunderstandings themselves - but some of their readers certainly did.

I've broken out the less controversial fixes into a separate PR:
https://github.com/D-Programming-Language/dlang.org/pull/629

On Thu, 14 Aug 2014 06:46:40 +0000
Andrew Godfrey via Digitalmars-d <digitalmars-d@puremagic.com> wrote:

sorry for the late answer.

> Don't think I'm being flippant, but I have trouble interpreting such feedback, because D's dynamic array semantics ARE complicated.
and it will be even more complicated if we will rename 'em to 'array references'.

i completely agree that D dynarray docs can be made clearer and i appreciate any efforts which makes docs better. i'm just against 'reference' term -- seems that i'm from that minority that becomes immediately confused when reading 'array reference'. what i expect from 'reference' is that this code works:

  void foo (int[] a) {
    a ~= 42;
  }
  ...
  int[] arr;
  arr ~= 666;
  foo(arr);
  assert(arr.length == 1 && arr[0] == 42);

but it doesn't. so arrays clearly aren't 'references' (as 'reference', to my opinion, should keep 'pass by reference' semantics in this case).

so maybe we should coin some new word to describe dynarrays in D.

On Sun, 17 Aug 2014 10:32:51 +0300
ketmar via Digitalmars-d <digitalmars-d@puremagic.com> wrote:

sorry, i meant THIS code:

   void foo (int[] a) {
     a ~= 42;
   }
   ...
   int[] arr;
   arr ~= 666;
   foo(arr);
   assert(arr.length == 2 && arr[1] == 42);

On Sunday, 17 August 2014 at 07:33:01 UTC, ketmar via Digitalmars-d wrote:
> On Thu, 14 Aug 2014 06:46:40 +0000
> Andrew Godfrey via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
>
> sorry for the late answer.
>
>> Don't think I'm being flippant, but I have trouble interpreting such feedback, because D's dynamic array semantics ARE complicated.
> and it will be even more complicated if we will rename 'em to 'array
> references'.
>
> i completely agree that D dynarray docs can be made clearer and i
> appreciate any efforts which makes docs better. i'm just against
> 'reference' term -- seems that i'm from that minority that becomes
> immediately confused when reading 'array reference'. what i expect from
> 'reference' is that this code works:
>
>   void foo (int[] a) {
>     a ~= 42;
>   }
>   ...
>   int[] arr;
>   arr ~= 666;
>   foo(arr);
>   assert(arr.length == 2 && arr[1] == 42);
>
> but it doesn't. so arrays clearly aren't 'references' (as 'reference',
> to my opinion, should keep 'pass by reference' semantics in this case).
>
> so maybe we should coin some new word to describe dynarrays in D.

Maybe. But consider that if "a" was a class and "~=" was instead
"=", you would have the same confusion. As in:
 void foo(MyClass a) {
    a = new MyClass;
 }

In either case, we are "passing a reference by value".
So operations on the referent affect the passed object/array, but operations
on the reference do not.

The further surprise is caused because concatenation affects the _reference_.
In fact it doesn't affect the referent at all!
Good example. Consider that this works:

void foo (int[] a) {
  a[0] = 42;
}

int[] arr;
arr ~= 666;
foo(arr);
assert(arr.length == 1 && arr[0] == 42);

On Tue, 19 Aug 2014 23:58:57 +0000
Andrew Godfrey via Digitalmars-d <digitalmars-d@puremagic.com> wrote:

> In either case, we are "passing a reference by value".
yes. but passing null class will not allow to call it's methods, and passing null array will. i.e.

  auto foo (MyClass a) { return a.length; }

will crash if length is not a static method (and it can't be static)
and foo is called like this: foo(null). but the same call will work for
'int[]'.

so user can assume that 'int[]' is something similar to class, and it's perfectly ok to use int[] methods, and '~=' is just the overloaded method, which should change contents of passed dynarray. again, overloaded '~=' will work for class (more or less), but will inevitably fail (i.e. will not change passed arg) for dynarray.

and it's clear that 'a = new MyClass()' creates new object. and it's not clear at all that 'a ~= 42' creates new object too. it's counterintuitive.

that's why i think that we need new term.

On Wednesday, 20 August 2014 at 00:13:32 UTC, ketmar via Digitalmars-d wrote:
> On Tue, 19 Aug 2014 23:58:57 +0000
> Andrew Godfrey via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
>
>> In either case, we are "passing a reference by value".
> yes. but passing null class will not allow to call it's methods, and
> passing null array will. i.e.
>
>   auto foo (MyClass a) { return a.length; }
>
> will crash if length is not a static method (and it can't be static)
> and foo is called like this: foo(null). but the same call will work for
> 'int[]'.
>
> so user can assume that 'int[]' is something similar to class, and it's
> perfectly ok to use int[] methods, and '~=' is just the overloaded
> method, which should change contents of passed dynarray. again,
> overloaded '~=' will work for class (more or less), but will
> inevitably fail (i.e. will not change passed arg) for dynarray.
>
> and it's clear that 'a = new MyClass()' creates new object. and it's
> not clear at all that 'a ~= 42' creates new object too. it's
> counterintuitive.
>
> that's why i think that we need new term.

Well, this is just one case of a general confusion that classes and dynamic arrays already share, by virtue of having hidden reference semantics (i.e. the "." operator dereferences in some cases and not in others, sometimes surprising novices).

You can see this in the existing array doc (http://dlang.org/arrays)
where it describes the "sizeof" property for dynamic arrays.
sizeof returns the size of the "dynamic array reference". A novice might expect it to return the size of the pointed-to array, to act more like the static-array case.