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

[kgryte]

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 for complex number instances in documentation examples. This is best conveyed through an example.

Consider the following JSDoc example in blas/ext/base/cfill:

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

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

/**
* ...
* 
*
* @example
* var Float32Array = require( '@stdlib/array/float32' );
* var Complex64Array = require( '@stdlib/array/complex64' );
* var Complex64 = require( '@stdlib/complex/float32/ctor' );
*
* var arr = new Float32Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
* var x = new Complex64Array( arr );
*
* var alpha = new Complex64( 10.0, 10.0 );
*
* cfill( x.length, alpha, x, 1 );
*
* var y = x.get( 0 );
* // returns <Complex64>[ 10.0, 10.0 ]
*/

Notice how, in the updated example, we use the doctest return annotation // returns <Complex64>[ 10.0, 10.0 ]. In contrast, in the old example, we decomposed an element into real and imaginary components.

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

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

If you compare the two example code blocks above, notice the removal of realf and imagf imports and element decomposition and updating the returns annotation to // returns <Complex64>[ 10.0, 10.0 ].

Steps

Given the relatively widespread practice of decomposing complex instances into individual components, 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/e8c8651693bc38d999b5f46cf31ccd370ad6cb8c, as this commit contains the sorts of changes that we are looking for.
1. Find a package containing documentation examples which performs element decomposition into real and imaginary components in order to show expected values. A possible global project search could use the regular expression \* var [a-zA-Z0-9]* = (?:real|imag)(?: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 complex number instance notation (e.g., <Complex64>[ ... ], <Complex128>[ ... ], 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
3. Submit a PR updating the documentation for that package (and only that package).
4. For the PR title, use the following template "docs: improve doctests for complex number instances in <package_name>", where <package_name> is the name of the package you updated (e.g., blas/ext/base/cfill).

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 complex number 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 complex number 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. 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.
• [x] Searched for existing issues and pull requests.
• [x] The issue name begins with RFC:.

[stdlib-bot]

:wave: Important: PLEASE READ :wave:

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.

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

[ashutoshsao]

encountered this error

while updating this file lib/node_modules/@stdlib/complex/base/wrap-function/docs/types/index.d.ts

maybe becasue this file uses realf and imagf inside function thats why

is this package not to be updated ?

[batpigandme]

@ashutoshsao I’m not sure about the answer to your question, but could you link to the lines in the example you’re changing in the code, e.g. https://github.com/stdlib-js/stdlib/blob/fea0656961ebe7b36ce35e6f13145b9c4d4c975d/lib/node_modules/%40stdlib/complex/base/wrap-function/docs/types/index.d.ts#L388-L404

or include the code as text (e.g. see the code chunks in Athan‘s issue description above)?

It’s much easier to read than screenshots of the text! Thanks 🙂

[kgryte]

@ashutoshsao For this particular package, you need to keep the import statements. The package can be updated, but as you guessed in your question, you need to keep those statements around as they are used for legitimate reasons in the function used in the example.

[ashutoshsao]

sure @batpigandme, @kgryte thanks for clarification.

[prajjwalbajpai]

@kgryte i was working on this issue for ./lib/node_modules/@stdlib/strided/base/cmap/

while commiting the changes i got the following lint error.

This error persisted after i tried to lint the file with all the changes removed.

Can you please help me fix it? Thanks

[Amansingh0807]

Hi @prajjwalbajpai, this error usually pops up when the linter plugins are not fully updated after a pull. I would say just run npm install in the root folder to refresh everything, and it should go away.

[prajjwalbajpai]

Thanks for helping @Amansingh0807!!

Hi @prajjwalbajpai, this error usually pops up when the linter plugins are not fully updated after a pull. I would say just run npm install in the root folder to refresh everything, and it should go away.

[kgryte]

@Amansingh0807 @prajjwalbajpai The provided advice above is not correct. You should not be manually running npm install in the root project folder. As documented in the development guide, you need to run make install-node-modules && make init. That is the first point. The second point is that you are not correctly running linting. We do not use npx. All of our linting is performed through make commands which set appropriate paths. If you attempt to run ESLint independently of our commands you will encounter errors like you see above.

[Amansingh0807]

@Amansingh0807 @prajjwalbajpai The provided advice above is not correct. You should not be manually running npm install in the root project folder. As documented in the development guide, you need to run make install-node-modules && make init. That is the first point. The second point is that you are not correctly running linting. We do not use npx. All of our linting is performed through make commands which set appropriate paths. If you attempt to run ESLint independently of our commands you will encounter errors like you see above.

Apologies for the incorrect advice and confusion here. I overlooked the specific build steps documented in the guide and defaulted to standard npm workflows. Thank you for pointing out the correct make commands.

[sujalcharati]

hey @kgryte i was working on this issue for ./lib/node_modules/@stdlib/math/base/special/cfloorn

while commiting the changes i got the following lint error. This error persisted after i tried to lint the file with all the changes removed as per the steps discussed in this issue #8975 let me know where i am going wrong below is the ERROR message and code snippet where i have changed as per required .

<!--



<section class="usage">

## Usage

```javascript
var cfloorn = require( '@stdlib/math/base/special/cfloorn' );

cfloorn( z, n )

Rounds each component of a double-precision complex floating-point number to the nearest multiple of 10^n toward negative infinity.

var Complex128 = require( '@stdlib/complex/float64/ctor' );

// Round components to 2 decimal places:
var v = cfloorn( new Complex128( -3.141592653589793, 3.141592653589793 ), -2 );
// returns <Complex128>[ -3.15, 3.14 ]

// If n = 0, `cfloorn` behaves like `cfloor`:
v = cfloorn( new Complex128( -3.141592653589793, 3.141592653589793 ), 0 );
// returns <Complex128>[ -4.0, 3.0 ]

// Round components to the nearest thousand:
v = cfloorn( new Complex128( -12368.0, 12368.0 ), 3 );
// returns <Complex128>[ -13000.0, 12000.0 ]

v = cfloorn( new Complex128( NaN, NaN ), 0 );
// returns <Complex128>[ NaN, NaN ]

Notes

• When operating on floating-point numbers in bases other than 2, rounding to specified digits can be inexact. For example,

  var Complex128 = require( '@stdlib/complex/float64/ctor' );
  
  var x = -0.2 - 0.1;
  // returns -0.30000000000000004
  
  // Should round components to 0.3:
  var v = cfloorn( new Complex128( x, x ), -16 );
  // returns <Complex128>[ -0.3000000000000001, -0.3000000000000001]
  

Examples

var Complex128 = require( '@stdlib/complex/float64/ctor' );
var uniform = require( '@stdlib/random/base/uniform' );
var randint = require( '@stdlib/random/base/discrete-uniform' );
var cfloorn = require( '@stdlib/math/base/special/cfloorn' );

var z;
var w;
var n;
var i;

for ( i = 0; i < 100; i++ ) {
    z = new Complex128( uniform( -50.0, 50.0 ), uniform( -50.0, 50.0 ) );

    n = randint( -5.0, 0.0 );
    w = cfloorn( z, n );

    console.log( 'floorn(%s,%s) = %s', z.toString(), n.toString(), w.toString() );
}

---

C APIs

Usage

#include "stdlib/math/base/special/cfloorn.h"

stdlib_base_cfloorn( z, n )

Rounds each component of a double-precision complex floating-point number to the nearest multiple of 10^n toward negative infinity.

#include "stdlib/complex/float64/ctor.h"
#include "stdlib/complex/float64/real.h"
#include "stdlib/complex/float64/imag.h"

stdlib_complex128_t z = stdlib_complex128( -3.141592653589793, 3.141592653589793 );
stdlib_complex128_t out = stdlib_base_cfloorn( z, -2 );

double re = stdlib_complex128_real( out );
// returns -3.15

double im = stdlib_complex128_imag( out );
// returns 3.14

The function accepts the following arguments:

• z: [in] stdlib_complex128_t input value.
• n: [in] int32_t integer power of 10.

stdlib_complex128_t stdlib_base_cfloorn( const stdlib_complex128_t z, const int32_t n );

Examples

#include "stdlib/math/base/special/cfloorn.h"
#include "stdlib/complex/float64/ctor.h"
#include "stdlib/complex/float64/reim.h"
#include <stdio.h>

int main() {
    const stdlib_complex128_t x[] = {
        stdlib_complex128( 3.14, 1.5 ),
        stdlib_complex128( -3.14, -1.5 ),
        stdlib_complex128( 0.0, 0.0 ),
        stdlib_complex128( 0.0/0.0, 0.0/0.0 )
    };

    stdlib_complex128_t v;
    stdlib_complex128_t y;
    double re1;
    double im1;
    double re2;
    double im2;
    int i;
    for ( i = 0; i < 4; i++ ) {
        v = x[ i ];
        y = stdlib_base_cfloorn( v, -2 );
        stdlib_complex128_reim( v, &re1, &im1 );
        stdlib_complex128_reim( y, &re2, &im2 );
        printf( "cfloorn(%lf + %lfi, -2) = %lf + %lfi\n", re1, im1, re2, im2 );
    }
}

---

See Also

• @stdlib/math/base/special/cceiln: round each component of a double-precision complex floating-point number to the nearest multiple of 10^n toward positive infinity.
• @stdlib/math/base/special/cfloor: round each component of a double-precision complex floating-point number toward negative infinity.
• @stdlib/math/base/special/croundn: round each component of a double-precision complex floating-point number to the nearest multiple of 10^n.

Can you please help me fix it?
Thanks