Merge pull request #4254 from wilzbach/ndslice_improve_docs

std.experimental.ndslice: improve docs
dlang · Apr 28, 2016 · 35eaf12 · 35eaf12
2 parents e56537d + 8fa0ffc
commit 35eaf12
Show file tree

Hide file tree

Showing 4 changed files with 53 additions and 44 deletions.
diff --git a/std/experimental/ndslice/iteration.d b/std/experimental/ndslice/iteration.d
@@ -9,24 +9,31 @@ All operators return slice of the same type as the type of the argument.
 
 $(BOOKTABLE $(H2 Transpose operators),
 
-$(TR $(TH Function Name) $(TH Descriprottion))
-$(T2 transposed, `iotaSlice(3, 4, 5, 6, 7).transposed!(4, 0, 1).shape` returns `[7, 3, 4, 5, 6]`.)
-$(T2 swapped, `iotaSlice(3, 4, 5).swapped!(1, 2).shape` returns `[3, 5, 4]`.)
-$(T2 everted, `iotaSlice(3, 4, 5).everted.shape` returns `[5, 4, 3]`.)
+$(TR $(TH Function Name) $(TH Description))
+$(T2 transposed, Permutes dimensions. $(BR)
+    `iotaSlice(3, 4, 5, 6, 7).transposed!(4, 0, 1).shape` returns `[7, 3, 4, 5, 6]`.)
+$(T2 swapped, Swaps dimensions $(BR)
+    `iotaSlice(3, 4, 5).swapped!(1, 2).shape` returns `[3, 5, 4]`.)
+$(T2 everted, Reverses the order of dimensions $(BR)
+    `iotaSlice(3, 4, 5).everted.shape` returns `[5, 4, 3]`.)
 )
 See also $(SUBREF selection, evertPack).
 
 $(BOOKTABLE $(H2 Iteration operators),
 
 $(TR $(TH Function Name) $(TH Description))
-$(T2 strided, `iotaSlice(13, 40).strided!(0, 1)(2, 5).shape` equals to `[7, 8]`.)
-$(T2 reversed, `slice.reversed!0` returns the slice with reversed direction of iteration for top level dimension.)
-$(T2 allReversed, `iotaSlice(4, 5).allReversed` equals to `20.iota.retro.sliced(4, 5)`.)
+$(T2 strided, Multiplies the stride of a selected dimension by a factor.$(BR)
+    `iotaSlice(13, 40).strided!(0, 1)(2, 5).shape` equals to `[7, 8]`.)
+$(T2 reversed, Reverses the direction of iteration for selected dimensions. $(BR)
+    `slice.reversed!0` returns the slice with reversed direction of iteration for top level dimension.)
+$(T2 allReversed, Reverses the direction of iteration for all dimensions. $(BR)
+    `iotaSlice(4, 5).allReversed` equals to `20.iota.retro.sliced(4, 5)`.)
 )
 
 $(BOOKTABLE $(H2 Other operators),
 $(TR $(TH Function Name) $(TH Description))
-$(T2 rotated, `iotaSlice(2, 3).rotated` equals to `[[2, 5], [1, 4], [0, 3]]`.)
+$(T2 rotated, Rotates two selected dimensions by `k*90` degrees. $(BR)
+    `iotaSlice(2, 3).rotated` equals to `[[2, 5], [1, 4], [0, 3]]`.)
 )
 
 $(H4 Drop operators)
@@ -484,7 +491,7 @@ Slice!(2, Range) transposed(Range)(auto ref Slice!(2, Range) slice)
         .shape == cast(size_t[5])[7, 3, 4, 5, 6]);
 }
 
-/// `2`-dimensional transpose
+/// _2-dimensional transpose
 @safe @nogc pure nothrow unittest
 {
     import std.experimental.ndslice.slice;
@@ -643,7 +650,7 @@ private enum _stridedCode = q{
 };
 
 /++
-Multiplies the stride of the selected dimension by the factor.
+Multiplies the stride of the selected dimension by a factor.
 
 Params:
     slice = input slice

diff --git a/std/experimental/ndslice/package.d b/std/experimental/ndslice/package.d
@@ -54,8 +54,9 @@ Quick_Start:
 $(SUBREF slice, sliced) is a function designed to create
 a multidimensional view over a range.
 Multidimensional view is presented by $(SUBREF slice, Slice) type.
+
 ------
-auto matrix = new double[12].sliced(3, 4);
+auto matrix = slice!double(3, 4);
 matrix[] = 0;
 matrix.diagonal[] = 1;
 
@@ -94,7 +95,7 @@ $(TR $(TDNW Basic Level
         $(SUBREF slice, SliceException)
     )
 )
-$(TR $(TDNW Middle Level
+$(TR $(TDNW Medium Level
         $(BR) $(SMALL Various iteration operators))
      $(TDNW $(SUBMODULE iteration))
      $(TD
@@ -147,7 +148,7 @@ reflected from the original image, and then applying the given function to the
 new file.
 
 Note: You can find the example at
-$(LINK2 https://github.com/DlangScience/examples/tree/master/image_processing/median-filter, GitHub).
+$(LINK2 https://github.com/libmir/mir/blob/master/examples/median_filter.d, GitHub).
 
 -------
 /++

diff --git a/std/experimental/ndslice/selection.d b/std/experimental/ndslice/selection.d
@@ -27,12 +27,12 @@ $(T2 evertPack, reverses dimension packs)
 $(BOOKTABLE $(H2 Selectors),
 
 $(TR $(TH Function Name) $(TH Description))
-$(T2 byElement, a random access range of all elements with `index` property)
+$(T2 byElement, flat, random access range of all elements with `index` property)
 $(T2 byElementInStandardSimplex, an input range of all elements in standard simplex of hypercube with `index` property.
     If the slice has two dimensions, it is a range of all elements of upper left triangular matrix.)
-$(T2 indexSlice, returns a lazy slice with elements equal to the initial multidimensional index)
-$(T2 iotaSlice, returns a lazy slice with elements equal to the initial flattened (continuous) index)
-$(T2 reshape, returns a new slice for the same data)
+$(T2 indexSlice, lazy slice with initial multidimensional index)
+$(T2 iotaSlice, lazy slice with initial flattened (continuous) index)
+$(T2 reshape, new slice with changed dimensions for the same data)
 $(T2 diagonal, 1-dimensional slice composed of diagonal elements)
 $(T2 blocks, n-dimensional slice composed of n-dimensional non-overlapping blocks.
     If the slice has two dimensions, it is a block matrix.)
@@ -69,7 +69,7 @@ Params:
     K = sizes of dimension packs
 Returns:
     `pack!K` returns `Slice!(N-K, Slice!(K+1, Range))`;
-    `slice.pack!(K1, K2, ..., Kn)` is the same as `slice.pacKed!K1.pacKed!K2. ... pacKed!Kn`.
+    `slice.pack!(K1, K2, ..., Kn)` is the same as `slice.pack!K1.pack!K2. ... pack!Kn`.
 +/
 template pack(K...)
 {
@@ -308,6 +308,7 @@ Slice!(1, Range) diagonal(size_t N, Range)(auto ref Slice!(N, Range) slice)
     assert(iotaSlice(2, 3).diagonal == d);
 }
 
+/// Non-square matrix
 @safe @nogc pure nothrow unittest
 {
     import std.algorithm.comparison: equal;
@@ -326,7 +327,7 @@ Slice!(1, Range) diagonal(size_t N, Range)(auto ref Slice!(N, Range) slice)
         .equal(only(0, 3)));
 }
 
-/// ditto
+/// Loop through diagonal
 pure nothrow unittest
 {
     import std.experimental.ndslice.slice;
@@ -690,7 +691,7 @@ pure nothrow unittest
 }
 
 /++
-Returns a new slice for the same data.
+Returns a new slice for the same data with different dimensions.
 
 Params:
     slice = slice to be reshaped
@@ -1559,7 +1560,7 @@ Params:
     lengths = list of dimension lengths
 Returns:
     `N`-dimensional slice composed of indexes
-See_also: $(LREF IndexSlice)
+See_also: $(LREF IndexSlice), $(LREF iotaSlice)
 +/
 IndexSlice!(Lengths.length) indexSlice(Lengths...)(Lengths lengths)
     if (allSatisfy!(isIndex, Lengths))
@@ -1663,7 +1664,7 @@ Params:
     shift = value of the first element in a slice
 Returns:
     `N`-dimensional slice composed of indexes
-See_also: $(LREF IotaSlice)
+See_also: $(LREF IotaSlice), $(LREF indexSlice)
 +/
 IotaSlice!(Lengths.length) iotaSlice(Lengths...)(Lengths lengths)
     if (allSatisfy!(isIndex, Lengths))

diff --git a/std/experimental/ndslice/slice.d b/std/experimental/ndslice/slice.d
@@ -889,19 +889,19 @@ in comments on operator overloading.
 
 $(BOOKTABLE
 $(TR $(TH Definition) $(TH Examples at `N == 3`))
-$(TR $(TD An $(BLUE interval) is a part of a sequence of type `i .. j`.)
+$(TR $(TD An $(B interval) is a part of a sequence of type `i .. j`.)
     $(STD `2..$-3`, `0..4`))
-$(TR $(TD An $(BLUE index) is a part of a sequence of type `i`.)
+$(TR $(TD An $(B index) is a part of a sequence of type `i`.)
     $(STD `3`, `$-1`))
-$(TR $(TD A $(BLUE partially defined slice) is a sequence composed of
-    $(BLUE intervals) and $(BLUE indexes) with an overall length strictly less than `N`.)
+$(TR $(TD A $(B partially defined slice) is a sequence composed of
+    $(B intervals) and $(B indexes) with an overall length strictly less than `N`.)
     $(STD `[3]`, `[0..$]`, `[3, 3]`, `[0..$,0..3]`, `[0..$,2]`))
-$(TR $(TD A $(BLUE fully defined index) is a sequence
-    composed only of $(BLUE indexes) with an overall length equal to `N`.)
+$(TR $(TD A $(B fully defined index) is a sequence
+    composed only of $(B indexes) with an overall length equal to `N`.)
     $(STD `[2,3,1]`))
-$(TR $(TD A $(BLUE fully defined slice) is an empty sequence
-    or a sequence composed of $(BLUE indexes) and at least one
-    $(BLUE interval) with an overall length equal to `N`.)
+$(TR $(TD A $(B fully defined slice) is an empty sequence
+    or a sequence composed of $(B indexes) and at least one
+    $(B interval) with an overall length equal to `N`.)
     $(STD `[]`, `[3..$,0..3,0..$-1]`, `[2,0..$,1]`))
 )
 
@@ -1605,7 +1605,7 @@ struct Slice(size_t _N, _Range)
     }
 
     /++
-    Returns: total number of elements in a slice
+    Returns: Total number of elements in a slice
     +/
     size_t elementsCount() const
     {
@@ -1700,7 +1700,7 @@ struct Slice(size_t _N, _Range)
     }
 
     /++
-    $(BLUE Fully defined index).
+    $(BOLD Fully defined index)
     +/
     auto ref opIndex(Repeat!(N, size_t) _indexes)
     {
@@ -1775,7 +1775,7 @@ struct Slice(size_t _N, _Range)
     }
 
     /++
-    $(BLUE Partially or fully defined slice).
+    $(BOLD Partially or fully defined slice.)
     +/
     auto opIndex(Slices...)(Slices slices)
         if (isPureSlice!Slices)
@@ -1925,7 +1925,7 @@ struct Slice(size_t _N, _Range)
         }
 
         /++
-        Assignment of a value of `Slice` type to a $(BLUE fully defined slice).
+        Assignment of a value of `Slice` type to a $(B fully defined slice).
         +/
         void opIndexAssign(size_t RN, RRange, Slices...)(Slice!(RN, RRange) value, Slices slices)
             if (isFullPureSlice!Slices
@@ -1974,7 +1974,7 @@ struct Slice(size_t _N, _Range)
         }
 
         /++
-        Assignment of a regular multidimensional array to a $(BLUE fully defined slice).
+        Assignment of a regular multidimensional array to a $(B fully defined slice).
         +/
         void opIndexAssign(T, Slices...)(T[] value, Slices slices)
             if (isFullPureSlice!Slices
@@ -2030,7 +2030,7 @@ struct Slice(size_t _N, _Range)
         }
 
         /++
-        Assignment of a value (e.g. a number) to a $(BLUE fully defined slice).
+        Assignment of a value (e.g. a number) to a $(B fully defined slice).
         +/
         void opIndexAssign(T, Slices...)(T value, Slices slices)
             if (isFullPureSlice!Slices
@@ -2090,7 +2090,7 @@ struct Slice(size_t _N, _Range)
         }
 
         /++
-        Assignment of a value (e.g. a number) to a $(BLUE fully defined index).
+        Assignment of a value (e.g. a number) to a $(B fully defined index).
         +/
         auto ref opIndexAssign(T)(T value, Repeat!(N, size_t) _indexes)
         {
@@ -2141,7 +2141,7 @@ struct Slice(size_t _N, _Range)
         }
 
         /++
-        Op Assignment `op=` of a value (e.g. a number) to a $(BLUE fully defined index).
+        Op Assignment `op=` of a value (e.g. a number) to a $(B fully defined index).
         +/
         auto ref opIndexOpAssign(string op, T)(T value, Repeat!(N, size_t) _indexes)
         {
@@ -2192,7 +2192,7 @@ struct Slice(size_t _N, _Range)
         }
 
         /++
-        Op Assignment `op=` of a value of `Slice` type to a $(BLUE fully defined slice).
+        Op Assignment `op=` of a value of `Slice` type to a $(B fully defined slice).
         +/
         void opIndexOpAssign(string op, size_t RN, RRange, Slices...)(Slice!(RN, RRange) value, Slices slices)
             if (isFullPureSlice!Slices
@@ -2241,7 +2241,7 @@ struct Slice(size_t _N, _Range)
         }
 
         /++
-        Op Assignment `op=` of a regular multidimensional array to a $(BLUE fully defined slice).
+        Op Assignment `op=` of a regular multidimensional array to a $(B fully defined slice).
         +/
         void opIndexOpAssign(string op, T, Slices...)(T[] value, Slices slices)
             if (isFullPureSlice!Slices
@@ -2289,7 +2289,7 @@ struct Slice(size_t _N, _Range)
         }
 
         /++
-        Op Assignment `op=` of a value (e.g. a number) to a $(BLUE fully defined slice).
+        Op Assignment `op=` of a value (e.g. a number) to a $(B fully defined slice).
         +/
         void opIndexOpAssign(string op, T, Slices...)(T value, Slices slices)
             if (isFullPureSlice!Slices
@@ -2331,7 +2331,7 @@ struct Slice(size_t _N, _Range)
         }
 
         /++
-        Increment `++` and Decrement `--` operators for a $(BLUE fully defined index).
+        Increment `++` and Decrement `--` operators for a $(B fully defined index).
         +/
         auto ref opIndexUnary(string op)(Repeat!(N, size_t) _indexes)
             if (op == `++` || op == `--`)
@@ -2384,7 +2384,7 @@ struct Slice(size_t _N, _Range)
         }
 
         /++
-        Increment `++` and Decrement `--` operators for a $(BLUE fully defined slice).
+        Increment `++` and Decrement `--` operators for a $(B fully defined slice).
         +/
         void opIndexUnary(string op, Slices...)(Slices slices)
             if (isFullPureSlice!Slices && (op == `++` || op == `--`))