docs(remark-run-javascript-examples): correct jsdoc example#12245
Draft
Planeshifter wants to merge 1 commit into
Draft
docs(remark-run-javascript-examples): correct jsdoc example#12245Planeshifter wants to merge 1 commit into
Planeshifter wants to merge 1 commit into
Conversation
The lint workflow (run 26260926243, 2026-05-22) failed on develop with
two errors in the `@example` block of `index.js`.
`stdlib/jsdoc-main-export` fired because the `str` array contained the
string literal `'var path = require( "path" );'`, placing a `require(`
substring in the description text after the main export's actual
`require()` call. The rule scans with `lastIndexOf('require(')` on the
raw description, so it treated the string literal as a trailing require
and concluded the main export was not last.
`stdlib/jsdoc-doctest` fired because the `// => 'HELLO WORLD'` comment
annotated `remark().use(run).process()` as returning the string
`'HELLO WORLD'`; the actual return value is the remark processor object.
Remove the usage-section lines (eliminating the offending string
literal) and drop the incorrect annotation. The example still
demonstrates the plugin's core behaviour: processing markdown that
contains a JavaScript examples section.
Ref: https://github.com/stdlib-js/stdlib/actions/runs/26260926243
stdlib-bot
added
Tools
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Resolves #12236.
Description
This pull request:
<section class="usage">block from the@exampleJSDoc tag inremark-run-javascript-examples/lib/index.jsthat causedstdlib/jsdoc-main-exportto fire a false positive by placing arequire( "path" )string literal after the main export's actualrequire()call.// => 'HELLO WORLD'return-value annotation from the same example, which causedstdlib/jsdoc-doctestto assert the processor call returns a string rather than the remark processor object.Related Issues
Questions
No.
Other
Failing CI: workflow run 26260926243 (2026-05-22T00:33:27Z, branch
develop).Error 1 —
stdlib/jsdoc-main-exportSymptom: "Example code of main export should require itself last."
Root cause: The
strarray in the example contained the string literal'var path = require( "path" );'. The lint rule locates the main export'srequire()by callinglastIndexOf('require(')on the raw tag description. That substring appeared inside the string literal at a higher offset than the actualrequire()call for the main export, somatch.index !== lastIndexOf('require(')evaluated totrueand the rule erroneously flagged the file.Fix: Removed the 14-line
<section class="usage">block containing the offending string literal.Error 2 —
stdlib/jsdoc-doctestSymptom: "Displayed return value is
'HELLO WORLD', but expectedfunction processor() {...}."Root cause: The
// => 'HELLO WORLD'annotation asserted thatremark().use(run).process()returns the string'HELLO WORLD'. The call actually returns the remark processor object.Fix: Removed the
// => 'HELLO WORLD'line.Validation: Three independent review agents (two opus, one sonnet) approved the diff or returned non-blocking findings only.
Checklist
AI Assistance
If you answered "yes" above, how did you use AI assistance?
Disclosure
This PR was authored by Claude Code as part of an automated CI-fix routine. The fix was validated by three independent review agents (two opus, one sonnet) before committing.
@stdlib-js/reviewers
Generated by Claude Code