fix: apply suggestions from code review

Author: headlessNode

lib/node_modules/@stdlib/ndarray/diagonal/README.md

@@ -22,6 +22,8 @@ limitations under the License.
 
 > Return a **read-only** view of the diagonal of a matrix (or stack of matrices).
 
+<!-- Section to include introductory text. Make sure to keep an empty line after the intro section element. -->
+
 <section class="intro">
 
 For an `M`-by-`N` matrix `A`, the `k`-th diagonal is defined as
@@ -39,12 +41,29 @@ D_k = \{\, A_{i,j} : j - i = k \,\}
 
 <!-- </equation> -->
 
-where `k = 0` corresponds to the main diagonal, `k > 0` corresponds to the super-diagonals (above the main diagonal), and `k < 0` corresponds to the sub-diagonals (below the main diagonal).
+where `k = 0` corresponds to the main diagonal, `k > 0` corresponds to the super-diagonals (above the main diagonal), and `k < 0` corresponds to the sub-diagonals (below the main diagonal). For example, given the matrix
+
+<!-- <equation class="equation" label="eq:diagonal_example" align="center" raw="A = \begin{bmatrix} a_{0,0} & a_{0,1} & a_{0,2} \\ a_{1,0} & a_{1,1} & a_{1,2} \\ a_{2,0} & a_{2,1} & a_{2,2} \end{bmatrix}" alt="Example matrix."> -->
+
+```math
+A = \begin{bmatrix} a_{0,0} & a_{0,1} & a_{0,2} \\ a_{1,0} & a_{1,1} & a_{1,2} \\ a_{2,0} & a_{2,1} & a_{2,2} \end{bmatrix}
+```
+
+<!-- <div class="equation" align="center" data-raw-text="A = \begin{bmatrix} a_{0,0} & a_{0,1} & a_{0,2} \\ a_{1,0} & a_{1,1} & a_{1,2} \\ a_{2,0} & a_{2,1} & a_{2,2} \end{bmatrix}" data-equation="eq:diagonal_example">
+    <img src="" alt="Example matrix.">
+    <br>
+</div> -->
+
+<!-- </equation> -->
+
+the main diagonal is `[ a_{0,0}, a_{1,1}, a_{2,2} ]`, the super-diagonal `k = 1` is `[ a_{0,1}, a_{1,2} ]`, and the sub-diagonal `k = -1` is `[ a_{1,0}, a_{2,1} ]`.
 
 </section>
 
 <!-- /.intro -->
 
+<!-- Package usage documentation. -->
+
 <section class="usage">
 
 ## Usage
@@ -55,7 +74,7 @@ var diagonal = require( '@stdlib/ndarray/diagonal' );
 
 #### diagonal( x\[, options] )
 
-Returns a read-only view of the diagonal of a matrix (or stack of matrices) `x`.
+Returns a read-only view of the diagonal of a matrix (or stack of matrices).
 
 ```javascript
 var array = require( '@stdlib/ndarray/array' );
@@ -81,6 +100,8 @@ The function accepts the following options:
 
 <!-- /.usage -->
 
+<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
 <section class="notes">
 
 ## Notes
@@ -92,6 +113,8 @@ The function accepts the following options:
 
 <!-- /.notes -->
 
+<!-- Package usage examples. -->
+
 <section class="examples">
 
 ## Examples
@@ -128,6 +151,8 @@ console.log( ndarray2array( y ) );
 
 <!-- /.examples -->
 
+<!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
 <section class="references">
 
 </section>

lib/node_modules/@stdlib/ndarray/diagonal/docs/repl.txt

@@ -9,12 +9,6 @@
 
     Each provided dimension index must reside on the interval [-ndims, ndims-1].
 
-    The diagonal offset `options.k` is interpreted as `column - row`.
-    Accordingly, when `options.k = 0`, the function returns the main diagonal;
-    when `options.k > 0`, the function returns the diagonal above the main
-    diagonal; and when `options.k < 0`, the function returns the diagonal
-    below the main diagonal.
-
     Parameters
     ----------
     x: ndarray
@@ -24,13 +18,19 @@
         Function options.
 
     options.k: integer (optional)
-        Diagonal offset. Default: 0.
+        Diagonal offset. The diagonal offset is interpreted as
+        `column - row`. Accordingly, when `options.k = 0`, the function
+        returns the main diagonal; when `options.k > 0`, the function returns
+        the diagonal above the main diagonal; and when `options.k < 0`, the
+        function returns the diagonal below the main diagonal. Default: 0.
 
     options.dims: ArrayLikeObject<integer> (optional)
         Dimension indices defining the plane from which to extract the
-        diagonal. Must contain exactly two unique dimension indices. If less
-        than zero, an index is resolved relative to the last dimension, with
-        the last dimension corresponding to the value `-1`. Default: [ -2, -1 ].
+        diagonal. The first element specifies the row-like dimension. The
+        second element specifies the column-like dimension. Must contain
+        exactly two unique dimension indices. If less than zero, an index is
+        resolved relative to the last dimension, with the last dimension
+        corresponding to the value `-1`. Default: [ -2, -1 ].
 
     Returns
     -------

lib/node_modules/@stdlib/ndarray/diagonal/docs/types/index.d.ts

@@ -50,7 +50,7 @@ interface Options {
 * @param x - input array
 * @param options - function options
 * @param options.k - diagonal offset (default: 0)
-* @param options.dims - dimension indices defining the plane from which to extract the diagonal.
+* @param options.dims - dimension indices defining the plane from which to extract the diagonal (default: [-2, -1])
 * @returns output array
 *
 * @example

lib/node_modules/@stdlib/ndarray/diagonal/lib/main.js

@@ -43,7 +43,7 @@ var format = require( '@stdlib/string/format' );
 * @param {ndarray} x - input array
 * @param {Options} [options] - function options
 * @param {integer} [options.k=0] - diagonal offset
-* @param {IntegerArray} [options.dims=[-2,-1]] - dimension indices defining the plane from which to extract the diagonal.
+* @param {IntegerArray} [options.dims=[-2,-1]] - dimension indices defining the plane from which to extract the diagonal
 * @throws {TypeError} first argument must be an ndarray
 * @throws {TypeError} options argument must be an object
 * @throws {TypeError} `k` option must be an integer