stdlib-js / stdlib-js/stdlib

[RFC]: Improve doctests for ndarray instances in documentation examples (tracking issue)

Open
#9,329 6 comments 0 reactions 0 assignees View on GitHub
Accepted difficulty: 1 Documentation Good First Issue JavaScript Modernization RFC Tracking Issue
Dominant language
JavaScript
Stars
6k
Forks
1.3k
Avg merge
1d 3h
Merged PRs (30d)
611

Description

### Instructions

1. Read the issue description below.
2. Read the issue comment which follows the description.
3. Search the code base for a package having a JSDoc example which needs updating according to the description below.
4. Follow any additional guidance specified in this issue.

### Description

This RFC proposes improving [doctests](https://github.com/stdlib-js/stdlib/blob/develop/docs/doctest.md) for ndarray instances in documentation examples. This is best conveyed through an example.

Consider the following JSDoc example in [`ndarray/count-falsy`](https://github.com/stdlib-js/stdlib/blob/67f4feb3b59fc5466e8302977634d3d5113467a8/lib/node_modules/%40stdlib/ndarray/count-falsy/lib/main.js):

```javascript
/**
* ...
*
* @example
* var Float64Array = require( '@stdlib/array/float64' );
* var ndarray = require( '@stdlib/ndarray/ctor' );
*
* // Create a data buffer:
* var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 0.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
*
* // Define the shape of the input array:
* var sh = [ 3, 1, 2 ];
*
* // Define the array strides:
* var sx = [ 4, 4, 1 ];
*
* // Define the index offset:
* var ox = 1;
*
* // Create an input ndarray:
* var x = new ndarray( 'float64', xbuf, sh, sx, ox, 'row-major' );
*
* // Perform reduction:
* var out = countFalsy( x );
* // returns
*
* var v = out.get();
* // returns 1
*/
```

Compare to the example after updating in commit https://github.com/stdlib-js/stdlib/commit/46d9a441ddf70ca13ac2a8d61cf54c628876e537

```javascript
/**
* ...
*
*
* @example
* var Float64Array = require( '@stdlib/array/float64' );
* var ndarray = require( '@stdlib/ndarray/ctor' );
*
* // Create a data buffer:
* var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 0.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
*
* // Define the shape of the input array:
* var sh = [ 3, 1, 2 ];
*
* // Define the array strides:
* var sx = [ 4, 4, 1 ];
*
* // Define the index offset:
* var ox = 1;
*
* // Create an input ndarray:
* var x = new ndarray( 'float64', xbuf, sh, sx, ox, 'row-major' );
*
* // Perform reduction:
* var out = countFalsy( x );
* // returns [ 1 ]
*/
```

Notice how, in the updated example, we use the [doctest](https://github.com/stdlib-js/stdlib/blob/develop/docs/doctest.md) return annotation `// returns [ 1 ]`. In contrast, in the old example, we explicitly access an ndarray element via the `get` method.

As may be observed, the updated doctest is much more compact and conveys more clearly the expected behavior.

Further consider the following example in the same package, as documented in the package's [README](https://github.com/stdlib-js/stdlib/tree/67f4feb3b59fc5466e8302977634d3d5113467a8/lib/node_modules/%40stdlib/ndarray/count-falsy)

```js
var array = require( '@stdlib/ndarray/array' );
var ndarray2array = require( '@stdlib/ndarray/to-array' );

// Create an input ndarray:
var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 0.0, 6.0 ] ] ] );
// returns

// Perform reduction:
var out = countFalsy( x, {
'dims': [ 1, 2 ]
});
// returns

var v = ndarray2array( out );
// returns [ 0, 0, 1 ]
```

Compare to the example after the same commit linked to above

```js
var array = require( '@stdlib/ndarray/array' );

// Create an input ndarray:
var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 0.0, 6.0 ] ] ] );
// returns

// Perform reduction:
var out = countFalsy( x, {
'dims': [ 1, 2 ]
});
// returns [ 0, 0, 1 ]
```

Notice how we removed the explicit usage of `ndarray2array` in favor of ndarray instance notation `[ 0, 0, 1 ]`, and, given that `ndarray2array` is no longer used in the example, we also removed the corresponding import (i.e., `require( '@stdlib/ndarray/to-array' )`.

Accordingly, this RFC seeks to leverage recent improvements in our [doctest](https://github.com/stdlib-js/stdlib/blob/develop/docs/doctest.md) framework which now supports nested ndarray instance notation for ndarray instances (e.g., `[ 1 ]`), where previously it did not; hence, the more verbose decomposition logic used in the first example.

### Steps

Given the relatively widespread practice of either manually accessing individual ndarray elements or using `ndarray2array` to convert ndarrays to nested arrays for the sole reason of showing expected results, this RFC aims to be an open call for any contributor wanting to contribute to the project to do the following:

0. Study the changes made in commit https://github.com/stdlib-js/stdlib/commit/46d9a441ddf70ca13ac2a8d61cf54c628876e537, as this commit contains the sorts of changes that we are looking for.
1. Find a package containing documentation examples which performs explicit element access or uses `ndarray2array` in order to show expected values. A possible global project search could use the regular expression `var [a-zA-Z0-9]* = (?:ndarray2array)(?:f|)\(`. From the search results, you should be able to find a package in need of updating.
2. Update the examples for that package, and **only that package**, to migrate to using ndarray instance notation (e.g., `[ ... ]`, etc). Examples may be found in the following package files (note: not all files may require updating; you should inspect each file individually):
- `README.md`
- `docs/index.d.ts`
- `docs/repl.txt`
- `examples/index.js`
- `lib/*` JSDoc examples
4. Submit a PR updating the documentation for that package (and only that package).
5. For the PR title, use the following template "docs: improve doctests for ndarray instances in ``", where `` is the name of the package you updated. For example,

```
docs: improve doctests for ndarray instances in `ndarray/count-falsy`
```

**Please do NOT make extraneous changes to examples. We are not interested in changing examples wholesale. We are only interested in replacing decomposition logic with ndarray instance notation.**

### Related Issues

None.

### Questions

No.

### Other

- If you are interested in working on this RFC, for each pull request, **please only update the examples for a single package**.
- As mentioned above, **please do NOT make extraneous changes to examples. We are not interested in changing examples wholesale. Nor are we interested in new "creative" changes. We are only interested in replacing decomposition logic with ndarray instance notation.** Failure to match the behavior of the existing examples and to respect this guidance will result in your PRs being automatically closed without review.
- As this is a "Good First Issue", you are **strongly encouraged** to **avoid** using AI when authoring your contribution. One of the primary intents of Good First Issues is to help introduce you to stdlib, its development environment, and the contribution process, as documented in the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md). Most new contributors are unfamiliar with stdlib and its conventions, and thus fail to appropriately use LLMs and AI when authoring contributions, most often generating AI slop and leading to wasted time. Don't be one of those people. :) Take the time to manually author your first several PRs, and, once you are intimately familiar with project conventions, you can consider leveraging AI to augment your dev tasks.

### Checklist

- [x] I have read and understood the [Code of Conduct](https://github.com/stdlib-js/stdlib/blob/develop/CODE_OF_CONDUCT.md).
- [x] Searched for existing issues and pull requests.
- [x] The issue name begins with `RFC:`.

Contributor guide

Open the contributing guide

Research direction

Read the doctest guidance and commit 46d9a441, then search for ndarray2array usage with the suggested regular expression. Inspect the matching package's README.md, docs/index.d.ts, docs/repl.txt, examples/index.js, and lib/* JSDoc examples. Done means updating one package only by replacing explicit ndarray decomposition with [ ... ] annotations and removing imports used solely for that decomposition.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.