On Fri, Jul 25, 2014 at 05:37:24PM +0000, Brad Anderson via Digitalmars-d wrote:
> On Friday, 25 July 2014 at 17:32:38 UTC, Andrei Alexandrescu wrote:
> >"Wyatt" <wyatt.epp@gmail.com> wrote:
> >>On Friday, 25 July 2014 at 15:59:18 UTC, Gary Willoughby wrote:
> >>>
> >>>The D community is hoping those discussion sections start being used in the same way the PHP documentation is used.
> >>
> >>We are?  Please, no.  Holding the PHP doc comments up as an example of a positive thing is alternately alternately hilarious and terrifying.
> >>
> >>-Wyatt
> >
> >Why? I don't have much context but a few people I talked to were positive about the community contribution to php docs. -- Andrei
> 
> They are hit or miss. Sometimes you'll find exactly what you need and sometimes you'll find terrible misinformation. I suspect this our community will fair better than PHP has here but there is still that risk.
> 
> I think it's worth a shot and if it becomes a problem the user comments can just be removed.

I'd suggest vetting user comments before posting them on the docs page, but that would mean requiring forumites to allocate yet more of their copious free time to the task. ;-)


T

-- 
Жил-был король когда-то, при нём блоха жила.

On Friday, 25 July 2014 at 17:32:38 UTC, Andrei Alexandrescu wrote:
> "Wyatt" <wyatt.epp@gmail.com> wrote:
>> On Friday, 25 July 2014 at 15:59:18 UTC, Gary Willoughby wrote:
>>> 
>>> The D community is hoping those discussion sections start being
>>> used in the same way the PHP documentation is used.
>> 
>> We are?  Please, no.  Holding the PHP doc comments up as an example of a
>> positive thing is alternately alternately hilarious and terrifying.
>> 
>> -Wyatt
>
> Why? I don't have much context but a few people I talked to were positive
> about the community contribution to php docs. -- Andrei

I've written about this before, but here's the summary:
There will be a comment thread on every single function in the standard library where people will say whatever they want and we can't stop them ahead of time.

- Anything they could possibly post there that's legitimately worth having would be better off canonised in the docs in the first place.
- Any questions they ask would be better asked on D.learn.
- Any other post may be subtly incorrect, previously correct, incredibly unsafe, correct with caveats, or a multitude of other shades of wrong.
- Everything else is noise.

We'd be better off wikifying the whole lot of it, and I don't say that lightly.  At least then there's the possibility of it being clear what's changing and who is changing it.

-Wyatt

On Friday, 25 July 2014 at 19:08:07 UTC, Wyatt wrote:
> I've written about this before, but here's the summary:
> There will be a comment thread on every single function in the standard library where people will say whatever they want and we can't stop them ahead of time.
>
> - Anything they could possibly post there that's legitimately worth having would be better off canonised in the docs in the first place.
> - Any questions they ask would be better asked on D.learn.
> - Any other post may be subtly incorrect, previously correct, incredibly unsafe, correct with caveats, or a multitude of other shades of wrong.
> - Everything else is noise.

Agreed. I find the idea of having the official docs cluttered with comments from literally anyone who could say anything (correct or not) to be a terrible idea.

- Jonathan M Davis

On Friday, 25 July 2014 at 17:32:38 UTC, Andrei Alexandrescu wrote:
> Why? I don't have much context but a few people I talked to were positive
> about the community contribution to php docs. -- Andrei

You have not been reading latest discussions about it carefully then ;)

(I also think it is bad idea)

On Saturday, 26 July 2014 at 01:48:11 UTC, Dicebot wrote:
> On Friday, 25 July 2014 at 17:32:38 UTC, Andrei Alexandrescu wrote:
>> Why? I don't have much context but a few people I talked to were positive
>> about the community contribution to php docs. -- Andrei
>
> You have not been reading latest discussions about it carefully then ;)
>
> (I also think it is bad idea)

So it's pretty much a consensus that it's a bad idea. I kinda agree that *any* comment shouldn't be allowed. However there is great knowledge in the community that would be nice to capture somehow.

On Friday, 25 July 2014 at 15:55:50 UTC, H. S. Teoh via Digitalmars-d wrote:
> On Fri, Jul 25, 2014 at 03:07:53PM +0000, Andrew Godfrey via Digitalmars-d wrote:
>> On Friday, 25 July 2014 at 04:38:40 UTC, Jonathan M Davis via Digitalmars-d
>> wrote:
>> >You really should read this article:
>> >
>> >http://dlang.org/d-array-article.html
>> 
>> Thank you, that was educational.
>> What I needed to read was that "A slice does not own the array, it
>> references the array." - which I knew, but I hadn't internalized that
>> even when a dynamic array is a private member, it is accessed via a
>> slice and the runtime is not aware when there's a 1-to-1
>> correspondence between the two.
>> 
>> The documentation could help a bit more. I'm game to
>> try to make a pull request for this, but I'm wondering
>> if the library docs can actually point to the article?
>
> That's a very good idea. I think that would dispel a lot of
> misconceptions that newcomers might have.
>
>
>> More feasibly, I'm thinking:
>> Both the documentation for length() (http://dlang.org/arrays)
>> and reserve() (http://dlang.org/phobos/std_array.html)
>> should at least mention assumeSafeAppend.
>> An example similar to what I posted may also be worthwhile.
> [...]
>
> Yes, please submit a PR for this.

So I've been looking into this, and I've realized the 'arrays' page is actually
inconsistent. (http://dlang.org/arrays).
Instead of spending time on a big update, I'll outline a proposal here.

This page generally uses the term "array" to mean the slice, and "array data"
to mean the allocated data that a slice currently refers to.
(In contrast, the handy article calls these "slice" and "dynamic array" respectively).

For example:

> Dynamic Arrays
> int[] a;

> Dynamic arrays consist of a length and a pointer to the array data. Multiple > dynamic arrays can share all or parts of the array data.

Problems start early on:

> Slicing

> Slicing an array means to specify a subarray of it. An array slice does not
> copy the data, it is only another reference to it.

By this page's terminology, this should actually say something like this:
"slicing an array means to specify a subarray of that array's current array data". e.g. Causing the first 'array' (slice) to grow would dissociate the slices from each other.

Because the term "slice" is so foreign,
I sympathize with how the term was avoided to start with. But the fact
is that a dynamic array declaration creates two separate things, and so
I'd propose to give them reliable names at the earliest.

So: Immediately after the section that introduces dynamic arrays, I would
then put the section on slices, and rather than describing a slice as a "subarray", I would introduce it as an important part of the workings
of a dynamic array. So I'm thinking the first example of a slice should be
a simplification of the article's example:

    int[] a = new int[5]; // A new dynamic array, with slice 'a' pointing to it.
    int[] b = a[];        // We now have two slices pointing to one dynamic array.

    a[1] = 42;
    assert(b[1] == 42);   // Demonstrating the point

Thereafter can come sub-slice examples and so on.
Does this make sense?

On Saturday, 26 July 2014 at 23:06:02 UTC, Andrew Godfrey wrote:
> Thereafter can come sub-slice examples and so on.
> Does this make sense?

Yes, the reference documentation is pretty terrible with naming of various array concepts.

IIRC, when this was discussed in the past, a majority seemed to be in favour of using "slice" and "dynamic array" for their respective concepts instead of the current situation, but I also remember there was some opposition (for reason I can't remember). A pull request updating the documentation to use slice/dynamic array might weed them out ;)

On Friday, 25 July 2014 at 17:32:38 UTC, Andrei Alexandrescu wrote:
> Why? I don't have much context but a few people I talked to were positive
> about the community contribution to php docs. -- Andrei

I find the php comments useful when I have to use the docs. It isn't about correctness, it is about gotchas and potential work-arounds. No worse than stack overflow.

There is noise, but it makes no difference at the bottom of the page. People are also more likely to comment there than submitting a formal complaint about errors in the docs.

On Sunday, 27 July 2014 at 06:06:03 UTC, Ola Fosheim Grøstad wrote:
> On Friday, 25 July 2014 at 17:32:38 UTC, Andrei Alexandrescu wrote:
>> Why? I don't have much context but a few people I talked to were positive
>> about the community contribution to php docs. -- Andrei
>
> I find the php comments useful when I have to use the docs. It isn't about correctness, it is about gotchas and potential work-arounds. No worse than stack overflow.
>
> There is noise, but it makes no difference at the bottom of the page. People are also more likely to comment there than submitting a formal complaint about errors in the docs.

Sure, it could be used as a lightweight bugtracker. But them, someone would have to watch the comments, and actually turn them into PRs, and remove the comments when the PRs are merged.

On Sunday, 27 July 2014 at 05:51:46 UTC, Jakob Ovrum wrote:
> On Saturday, 26 July 2014 at 23:06:02 UTC, Andrew Godfrey wrote:
>> Thereafter can come sub-slice examples and so on.
>> Does this make sense?
>
> Yes, the reference documentation is pretty terrible with naming of various array concepts.
>
> IIRC, when this was discussed in the past, a majority seemed to be in favour of using "slice" and "dynamic array" for their respective concepts instead of the current situation, but I also remember there was some opposition (for reason I can't remember). A pull request updating the documentation to use slice/dynamic array might weed them out ;)

As defined by the language, T[] is a dynamic array. As great as the article is, it was wrong in its use of the terminology, and that's what's caused a lot of the confusion and resulted in arguments over the difference between a dynamic array and a slice (there really isn't any). IIRC, both Walter and Andrei stated in that discussion that T[] is a dynamic array as far as D is concerned and that's not going to change. The article really should be updated to reflect the correct terminology. As far as D is concerned a slice and a dynamic array are the same thing when it comes to arrays. They're just different names for T[], and trying to treat them as different just causes confusion.

- Jonathan M Davis