On Monday, 28 December 2015 at 21:43:35 UTC, Robert burner Schadek wrote:
> On Monday, 28 December 2015 at 18:39:47 UTC, Ilya Yaroshenko wrote:
>> Have you read the latest changes?
>> http://forum.dlang.org/post/djgkkrdufycyjhpmafse@forum.dlang.org
>>
>
> I have.
>
> The problem with the doc is that is describes what it can be used for, but it does not describe what it is.
>
> It is like saying: "It brings you from point A to point B."
> Instead you should say it is a car. And a car is self moving object ....
>
> The first few sentences:
> """
> The package is designed for applications such as linear algebra, physics and statistics. It would be well suited to creating machine learning and image processing algorithms, but should also be general enough for use anywhere with homogeneously-typed multidimensional data.
> """
> does not say what it is.
>
> Should be something, as far as I understand the package, like:
>
> """
> This package provides a multidimensional array implementation, suited for scientific computing. Additionally, many functions for iteration, accessing and manipulation are given. ....
> """

Agreed

1. First paragraph was replaced by your variant.
2. Binary representation was moved to Slice type documentation.
3. Small "Quick Start" was added, so new user will start from `sliced` and `Slice`.

http://dtest.thecybershadow.net/artifact/website-76234ca0eab431527327d5ce1ec0ad74c6421533-081dd6e9e8b3810a143d0a5fcba8d60b/web/phobos-prerelease/std_experimental_ndslice.html

Thanks!

Ilya

On Monday, 28 December 2015 at 22:39:45 UTC, Ilya Yaroshenko wrote:
> On Monday, 28 December 2015 at 21:43:35 UTC, Robert burner Schadek wrote:
>> [...]
>
> Agreed
>
> 1. First paragraph was replaced by your variant.
> 2. Binary representation was moved to Slice type documentation.
> 3. Small "Quick Start" was added, so new user will start from `sliced` and `Slice`.
>
> http://dtest.thecybershadow.net/artifact/website-76234ca0eab431527327d5ce1ec0ad74c6421533-081dd6e9e8b3810a143d0a5fcba8d60b/web/phobos-prerelease/std_experimental_ndslice.html
>
> Thanks!
>
> Ilya

Fix English: http://dtest.thecybershadow.net/artifact/website-76234ca0eab431527327d5ce1ec0ad74c6421533-bfed2500425eb407bf2c97fc72e8a0c5/web/phobos-prerelease/std_experimental_ndslice.html

On Tuesday, 29 December 2015 at 07:45:14 UTC, Ilya Yaroshenko wrote:
> On Monday, 28 December 2015 at 22:39:45 UTC, Ilya Yaroshenko wrote:
>> On Monday, 28 December 2015 at 21:43:35 UTC, Robert burner Schadek wrote:
>>> [...]
>>
>> Agreed
>>
>> 1. First paragraph was replaced by your variant.
>> 2. Binary representation was moved to Slice type documentation.
>> 3. Small "Quick Start" was added, so new user will start from `sliced` and `Slice`.
>>
>> http://dtest.thecybershadow.net/artifact/website-76234ca0eab431527327d5ce1ec0ad74c6421533-081dd6e9e8b3810a143d0a5fcba8d60b/web/phobos-prerelease/std_experimental_ndslice.html
>>
>> Thanks!
>>
>> Ilya
>
> Fix English: http://dtest.thecybershadow.net/artifact/website-76234ca0eab431527327d5ce1ec0ad74c6421533-bfed2500425eb407bf2c97fc72e8a0c5/web/phobos-prerelease/std_experimental_ndslice.html

If I am reading the code right, the number of dimensions must always be known at compile time, right? Is so, I suppose it was a performance-oriented decision and not an oversight, correct?

On Tuesday, 29 December 2015 at 13:30:47 UTC, Márcio Martins wrote:
> If I am reading the code right, the number of dimensions must always be known at compile time, right?

Not necessarily. The dimensions for this slice are computed at runtime.

```
auto slice = 1000.iota.sliced(5, 6, 7);
```

On Tuesday, 29 December 2015 at 13:54:56 UTC, Jack Stouffer wrote:
> On Tuesday, 29 December 2015 at 13:30:47 UTC, Márcio Martins wrote:
>> If I am reading the code right, the number of dimensions must always be known at compile time, right?
>
> Not necessarily. The dimensions for this slice are computed at runtime.
>
> ```
> auto slice = 1000.iota.sliced(5, 6, 7);
> ```

```

With this declaration:

```
struct Slice(size_t _N, _Range)
```
_N, the number of dimensions, must necessarily be known at compile-time, right?

On Monday, 28 December 2015 at 22:39:45 UTC, Ilya Yaroshenko wrote:
>
> 1. First paragraph was replaced by your variant.
> 2. Binary representation was moved to Slice type documentation.
> 3. Small "Quick Start" was added, so new user will start from `sliced` and `Slice`.

That is just patchwork ...

The style of writing I presented should be used throughout the documentation so people know what everything is and how it works together.

On Tuesday, 29 December 2015 at 14:51:37 UTC, Márcio Martins wrote:
> On Tuesday, 29 December 2015 at 13:54:56 UTC, Jack Stouffer wrote:
>> On Tuesday, 29 December 2015 at 13:30:47 UTC, Márcio Martins wrote:
>>> If I am reading the code right, the number of dimensions must always be known at compile time, right?
>>
>> Not necessarily. The dimensions for this slice are computed at runtime.
>>
>> ```
>> auto slice = 1000.iota.sliced(5, 6, 7);
>> ```
>
> ```
>
> With this declaration:
>
> ```
> struct Slice(size_t _N, _Range)
> ```
> _N, the number of dimensions, must necessarily be known at compile-time, right?

Yes. -- Ilya

On Tuesday, 29 December 2015 at 13:30:47 UTC, Márcio Martins wrote:
> On Tuesday, 29 December 2015 at 07:45:14 UTC, Ilya Yaroshenko wrote:
>> On Monday, 28 December 2015 at 22:39:45 UTC, Ilya Yaroshenko wrote:
>>> On Monday, 28 December 2015 at 21:43:35 UTC, Robert burner Schadek wrote:
>>>> [...]
>>>
>>> Agreed
>>>
>>> 1. First paragraph was replaced by your variant.
>>> 2. Binary representation was moved to Slice type documentation.
>>> 3. Small "Quick Start" was added, so new user will start from `sliced` and `Slice`.
>>>
>>> http://dtest.thecybershadow.net/artifact/website-76234ca0eab431527327d5ce1ec0ad74c6421533-081dd6e9e8b3810a143d0a5fcba8d60b/web/phobos-prerelease/std_experimental_ndslice.html
>>>
>>> Thanks!
>>>
>>> Ilya
>>
>> Fix English: http://dtest.thecybershadow.net/artifact/website-76234ca0eab431527327d5ce1ec0ad74c6421533-bfed2500425eb407bf2c97fc72e8a0c5/web/phobos-prerelease/std_experimental_ndslice.html
>
> If I am reading the code right, the number of dimensions must always be known at compile time, right? Is so, I suppose it was a performance-oriented decision and not an oversight, correct?

This package is performance oriented. In the same time it is more flexible comparing with numpy.

Simple optimisation check:
Source: https://gist.github.com/9il/bc7966823d96557c566c
LDC disassembled: https://gist.github.com/9il/47aea1621a9fba609869 (all functions are inlined)

On Tuesday, 29 December 2015 at 15:42:32 UTC, Robert burner Schadek wrote:
> On Monday, 28 December 2015 at 22:39:45 UTC, Ilya Yaroshenko wrote:
>>
>> 1. First paragraph was replaced by your variant.
>> 2. Binary representation was moved to Slice type documentation.
>> 3. Small "Quick Start" was added, so new user will start from `sliced` and `Slice`.
>
> That is just patchwork ...
>
> The style of writing I presented should be used throughout the documentation so people know what everything is and how it works together.

OK, lets discuss every function.

Fist is `transposed`:

-------
N-dimensional transpose operator. Brings selected dimensions to the first position.

Parameters:
Slice!(N, Range) slice	input slice
Dimensions	indexes of dimensions to be brought to the first position

Returns:
n-dimensional slice of the same type
See Also:
swapped, everted
------------

What is wrong with this documentation?

On Tuesday, 29 December 2015 at 16:11:00 UTC, Ilya Yaroshenko wrote:
>
> OK, lets discuss every function.
>

That is acceptably the problem. It is not about the documentation of the functions it is about the documentation binding the functions together and the documentation giving the idea of the library.