[RFC]: Improve doctests for complex number typed arrays in documentation examples

[kgryte]

Description

This RFC proposes improving doctests for complex number typed arrays in documentation examples. This is best conveyed through an example.

Consider the following JSDoc example in blas/base/ccopy:

/**
* ...
*
* @example
* var Complex64Array = require( '@stdlib/array/complex64' );
* var realf = require( '@stdlib/complex/float32/real' );
* var imagf = require( '@stdlib/complex/float32/imag' );
*
* var x = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
* var y = new Complex64Array( [ 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
*
* ccopy( x.length, x, 1, y, 1 );
*
* var z = y.get( 0 );
* // returns <Complex64>
*
* var re = realf( z );
* // returns 1.0
*
* var im = imagf( z );
* // returns 2.0
*/

Compare to a similar example from blas/base/dcopy.

/**
* ...
* 
*
* @example
* var Float64Array = require( '@stdlib/array/float64' );
*
* var x = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] );
* var y = new Float64Array( [ 6.0, 7.0, 8.0, 9.0, 10.0 ] );
*
* dcopy( x.length, x, 1, y, 1 );
* // y => <Float64Array>[ 1.0, 2.0, 3.0, 4.0, 5.0 ]
*/

Notice how, for dcopy, we use the doctest return annotation // y => <Float64Array>[ ... ]; however, for ccopy, we need to retrieve an individual element and then decompose into real and imaginary components.

As may be observed, the dcopy doctest is much more compact and conveys much more clearly the expected behavior. For the complex number typed array case, in order to show the expected behavior for the entire typed array, we'd need to extract and decompose each individual element. This is both more tedious when authoring documentation and less effective as a means of conveying expected behavior.

Accordingly, this RFC seeks to leverage recent improvements in our doctest framework which now supports typed array instance notation for complex number typed arrays (e.g., <Complex64Array>[ 1.0, 2.0, 3.0, 4.0 ]), where previously it did not; hence, the more verbose decomposition logic.

Revisiting ccopy above to use typed array instance notation would yield

/**
* ...
*
* @example
* var Complex64Array = require( '@stdlib/array/complex64' );
*
* var x = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
* var y = new Complex64Array( [ 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
*
* ccopy( x.length, x, 1, y, 1 );
* // y => <Complex64Array>[ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ]
*/

Notice the removal of realf and imagf imports and element decomposition and the insertion of // y => <Complex64Array>[ ... ].

Given the relatively widespread practice of decomposing a complex number typed array into individual components, this RFC aims to be an open call for any contributor wanting to contributor to the project to do the following:

1. Find a package containing documentation examples which performs element decomposition into real and imaginary components in order to show expected values.
2. Update the examples for that package, and only that package, to migrate to using typed array instance notation (e.g., <Complex64Array>[ ... ], <Complex128Array>[ ... ], etc). Examples may be found in the package
   • README
   • TypeScript declarations
   • REPL text
   • examples/index.js
   • lib/* JSDoc examples
3. Submit a PR updating the documentation for that package (and only that package).

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 typed array 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 typed array 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.

Checklist

• I have read and understood the Code of Conduct.
• Searched for existing issues and pull requests.
• The issue name begins with RFC:.

[stdlib-bot]

👋 Important: PLEASE READ 👋

This issue has been labeled as a good first issue and is available for anyone to work on.

If this is your first time contributing to an open source project, some aspects of the development process may seem unusual, arcane, or some combination of both.

1. You cannot "claim" issues. People new to open source often want to "claim" or be assigned an issue before beginning work. The typical rationale is that people want to avoid wasted work in the event that someone else ends up working the issue. However, this practice is not effective in open source, as it often leads to "issue squatting", in which an individual asks to be assigned, is granted their request, and then never ends up working on the issue. Accordingly, you are encouraged to communicate your intent to address this issue, ideally by providing a rough outline as to how you plan to address the issue or asking clarifying questions, but, at the end of the day, we will take running code and rough consensus in order to move forward quickly.
2. We have a very high bar for contributions. We have very high standards for contributions and expect all contributions—whether new features, tests, or documentation—to be rigorous, thorough, and complete. Once a pull request is merged into stdlib, that contribution immediately becomes the collective responsibility of all maintainers of stdlib. When we merge code into stdlib, we are saying that we, the maintainers, commit to reviewing subsequent changes and making bugfixes to the code. Hence, in order to ensure future maintainability, this naturally leads to a higher standard of contribution.

Before working on this issue and opening a pull request, please read the project's contributing guidelines. These guidelines and the associated development guide provide important information, including links to stdlib's Code of Conduct, license policy, and steps for setting up your local development environment.

To reiterate, we strongly encourage you to refer to our contributing guides before beginning work on this issue. Failure to follow our guidelines significantly decreases the likelihood that you'll successfully contribute to stdlib and may result in automatic closure of a pull request without review.

Setting up your local development environment is a critical first step, as doing so ensures that automated development processes for linting, license verification, and unit testing can run prior to authoring commits and pushing changes. If you would prefer to avoid manual setup, we provide pre-configured development containers for use locally or in GitHub Codespaces.

We place a high value on consistency throughout the stdlib codebase. We encourage you to closely examine other packages in stdlib and attempt to emulate the practices and conventions found therein.

• If you are attempting to contribute a new package, sometimes the best approach is to simply copy the contents of an existing package and then modify the minimum amount necessary to implement the feature (e.g., changing descriptions, parameter names, and implementation).
• If you are contributing tests, find a package implementing a similar feature and emulate the tests of that package.
• If you are updating documentation, examine several similar packages and emulate the content, style, and prose of those packages.

In short, the more effort you put in to ensure that your contribution looks and feels like stdlib—including variables names, bracket spacing, line breaks, etc—the more likely that your contribution will be reviewed and ultimately accepted. We encourage you to closely study the codebase before beginning work on this issue.

✨ Thank you again for your interest in stdlib, and we look forward to reviewing your future contributions. ✨

[gautam-krishna-sharma]

hello can i solve this by doing the things like

1 Remove imports for realf and imagf:

var realf = require( '@stdlib/complex/float32/real' );
var imagf = require( '@stdlib/complex/float32/imag' );
— Remove these lines.

2. Remove logic for extracting and decomposing real and imaginary components:
   var z = y.get( 0 );
   var re = realf( z );
   var im = imagf( z );
   — Remove these lines.

3. Add a single-line comment showing the expected output using typed array instance notation:

Edit
// y => [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ]

@kgryte please review and suggest me that can i solve it like this

[kgryte]

@gautam-krishna-sharma What you describe is essentially what I wrote in the OP. The only thing I will add is that whether you use <var> => <Complex64Array>[ ... ] or returns <Complex64Array>[ ... ] depends on the example and its context. You should read the doctest guide, as linked in the OP, to understand the difference.