Voting For std.experimental.ndslice

[Ilya Yaroshenko via Digitalmars-d]

On Tuesday, 29 December 2015 at 16:28:52 UTC, Robert burner 
Schadek wrote:
> 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.

OK, looks like I understand you.

My style of exploration is set of examples. For some people it is 
much better. But I agree that it may be bad for others.

About `iteration` module:
====================
1. from documentation:
------
Operators only change strides and lengths of a slice. The range 
of a slice remains unmodified. All operators return slice of the 
same type as the type of the argument.
------
2. They are very simple functions, and their combination is 
simple too. A user will understand how to use them. Furthermore 
`Binary representation` section in `Slice` docs has examples with 
`transposed` and `reversed`. So user can understand what exactly 
going on with iteration functions.


About selection module:
====================
1. from documentation:
------
Selectors create new views and iteration patterns over the same 
data, without copying.

Subspace selectors
- - -
Subspace selectors serve to generalize and combine other 
selectors easily. For a slice of Slice!(N, Range) type 
slice.pack!K creates a slice of slices of Slice!(N-K, Slice!(K+1, 
Range)) type by packing the last K dimensions of the top 
dimension pack, and the type of element of slice.byElement is 
Slice!(K, Range). Another way to use pack is transposition of 
dimension packs using evertPack. Examples of use of subspace 
selectors are available for selectors, Slice.shape , and 
Slice.elementsCount .
------

2. Selectors look simple, but their combinations can be _very_ 
crazy. Combination of this functions is art of imagination. I am 
not so talented writer to create good documentation. The problem 
here is that I have never discuss this module with significant 
amount of people. And I don't think that I will have such 
opportunity. So what I have done with documentation for 
selectors? I created cross examples:

`unpack` has examples with
   - `pack`
`evertPack` has examples with
   - `pack`
   - `unpack`
`diagonal` has examples with
   - `dropOne`
   - `dropToHypercube`
   - `reversed`
   - `pack`
   - `evertPack`
   - Note about additional examples with `blocks` and `windows`
`blocks` has examples with
   - `byElement`
   - `diagonal`
   - `pack`
   - `evertPack`
   - `unpack`
`windows` has examples with
   - `byElement`
   - `diagonal`
   - `pack`
   - `evertPack`
   - `unpack`
`byElement` has examples with
   - `pack`
   - `drop`
   - `std.range.retro`
   - `allReversed`
`byElementInStandardSimplex` has examples with
   - `allReversed `
   - `transposed`
`indexSlice` has examples with
   - `byElement`

In addition, example `Image Processing` in `package` description 
is a real world combination of `sliced`, `pack`, `windows`, 
`unpack`, `byElement`, `std.algorithm.iteration.map`, 
`std.array.array`,  `Slice.shape`.

This is a way how I can write documentation. I don't think that I 
can write using style you want or find someone who can do it 
instead of me. I am already spend a lot of time with English 
translator to improve docs. And every new sentence is a real 
pain, because I need to ask my translator to check it.

Ilya