docs: add comments

---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
  - task: lint_filenames
    status: passed
  - task: lint_editorconfig
    status: passed
  - task: lint_markdown
    status: na
  - task: lint_package_json
    status: na
  - task: lint_repl_help
    status: na
  - task: lint_javascript_src
    status: passed
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: na
  - task: lint_javascript_tests
    status: na
  - task: lint_javascript_benchmarks
    status: na
  - task: lint_python
    status: na
  - task: lint_r
    status: na
  - task: lint_c_src
    status: na
  - task: lint_c_examples
    status: na
  - task: lint_c_benchmarks
    status: na
  - task: lint_c_tests_fixtures
    status: na
  - task: lint_shell
    status: na
  - task: lint_typescript_declarations
    status: passed
  - task: lint_typescript_tests
    status: na
  - task: lint_license_headers
    status: passed
---

Author: kgryte

lib/node_modules/@stdlib/_tools/doctest/compare-values/lib/main.js

@@ -472,6 +472,7 @@ function compareValues( actual, expected ) {
 	var a;
 	var b;
 
+	// Case: compareValues( true, 'true || false' )
 	if ( contains( expected, '||' ) ) {
 		parts = expected.split( '||' );
 		a = trim( parts[ 0 ] );
@@ -483,23 +484,28 @@ function compareValues( actual, expected ) {
 		}
 		return null;
 	}
+	// Case: compareValues( ???, '' )
 	if ( isEmptyString( expected ) ) {
 		return 'Return annotation is empty';
 	}
+	// Case: compareValues( ???, 'e.g., returns 5' )
 	if ( contains( expected, 'e.g.' ) ) {
 		// Early return since we cannot compare actual value to return annotation value:
 		return null;
 	}
+	// Case: compareValues( [], '<Array>' )
 	if ( startsWith( expected, '<' ) && endsWith( expected, '>' ) ) {
 		if ( !checkForPlaceholders( actual, expected ) ) {
 			return 'Expected a '+expected+', but received: `'+actual+'`';
 		}
+		// Case: compareValues( new Number( 5 ), '<Number>' )
 		if (
 			contains( BOXED_TYPE_ANNOTATIONS, expected ) &&
 			isPrimitive( actual )
 		) {
 			return 'Expected a '+expected+', but received an unboxed primitive: `'+actual+'`';
 		}
+		// Case: compareValues( 5, '<number>' )
 		if (
 			contains( PRIMITIVE_TYPE_ANNOTATIONS, expected ) &&
 			isBoxedPrimitive( actual )
@@ -508,6 +514,7 @@ function compareValues( actual, expected ) {
 		}
 		return null;
 	}
+	// Case: compareValues( 5, '5' )
 	if ( isPrimitive( actual ) ) {
 		if ( isString( actual) ) {
 			if (
@@ -523,32 +530,38 @@ function compareValues( actual, expected ) {
 		}
 		return null;
 	}
-	if ( isTypedArray( actual ) || isComplexTypedArray( actual ) || isBooleanArray( actual ) ) {
+	// Case: compareValues( new Float64Array( [ 1.0, 2.0 ] ), '<Float64Array>[ 1.0, 2.0 ]' )
+	if ( isTypedArray( actual ) || isComplexTypedArray( actual ) || isBooleanArray( actual ) ) { // eslint-disable-line max-len
 		return checkTypedArrays( actual, expected );
 	}
+	// Case: compareValues( [ 1.0, 2.0 ], '[ 1.0, 2.0 ]' )
 	if ( isArray( actual ) ) {
 		if ( !checkArray( actual, expected ) ) {
 			return 'Displayed return value is `'+expected+'`, but expected `'+createAnnotationValue( actual )+'` instead';
 		}
 		return null;
 	}
+	// Case: compareValues( new Complex64( 1.0, 2.0 ), '<Complex64>[ 1.0, 2.0 ]' )
 	if ( isComplex64( actual ) || isComplex128( actual ) ) {
 		return checkComplex( actual, expected );
 	}
+	// Case: compareValues( /foo/, '/foo/' )
 	if ( isRegExp( actual ) ) {
 		actual = actual.toString();
 		if ( actual !== expected ) {
 			return 'Displayed return value is `'+expected+'`, but expected `'+actual+'` instead';
 		}
 		return null;
 	}
+	// Case: compareValues( function noop() {}, 'function noop() {}' )
 	if ( isFunction( actual ) ) {
 		actual = actual.toString();
 		if ( actual !== expected ) {
 			return 'Displayed return value is `'+expected+'`, but expected `'+actual+'` instead';
 		}
 		return null;
 	}
+	// Case: compareValues( {}, '{}' )
 	if ( isObjectLike( actual ) ) {
 		if ( !contains( expected, '...' ) ) {
 			try {