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
