docs: fix incomplete example and missing @private tag in _tools/remark/plugins

[Planeshifter]

Description

What is the purpose of this pull request?

This pull request:

• brings two @stdlib/_tools/remark/plugins packages into line with JSDoc conventions that the rest of the namespace follows (≥93% conformance). The changes are documentation-only and do not alter behavior.

Namespace summary

• Namespace: @stdlib/_tools/remark/plugins, 14 members, none autogenerated. Majority threshold: ≥11/14 (75%).
• Features analyzed: file tree; package.json key sets and values; README ##/### heading order and <section> classes; test/benchmark/example filenames; and, per package, the public signature, return kind, validation prologue, error construction, JSDoc shape (exported and internal functions), @stdlib/* dependencies, and the module-level @example.
• Clear majority (≥75%), fully conformant: file tree core (README.md, package.json, lib/index.js, examples/index.js), package.json top-level keys, README heading order (Usage → [Notes] → Examples), and format-based construction for every thrown Error/TypeError (12/12 packages that construct errors).
• Clear majority (≥75%), with outliers (corrected here): module @example invokes remark().use( <plugin> ) (13/14); every internal function JSDoc carries @private (13/14).
• No clear majority (excluded): engines.node (>=0.10.0 vs >=6.0.0, 8/6), directories.test (4/14), test/ presence (4/14), the mdast keyword (9/14), presence of an options argument (10/14), the isObject options check (9/14), and @example on the exported function (4/14).

@stdlib/_tools/remark/plugins/remark-lint-html-section-structure

The module-level JSDoc @example in lib/index.js declared str and done but never ran the plugin. Added remark().use( lint ).process( str, done );, matching remark-lint-equations. 13 of 14 sibling plugins (93%) invoke remark().use( <plugin> ) in the module example. Doc-only; no behavior change.

@stdlib/_tools/remark/plugins/remark-svg-equations-to-file

Added the missing @private JSDoc tag to the internal onWrite callback in lib/transformer.js. Every other internal function in the file (transformer, visitor, onDir, next, onSVG, done) already carries the tag, and tagging every non-exported function @private is the convention in 13 of 14 namespace packages (93%). This also satisfies the stdlib/jsdoc-private-annotation lint rule. Doc-only; no behavior change.

Related Issues

Does this pull request have any related issues?

No.

Questions

Any questions for reviewers of this pull request?

No.

Other

Any other information relevant to this pull request? This may include screenshots, references, and/or implementation notes.

Validation

• Structural extraction via filesystem and string scans over all 14 members.
• Semantic extraction via one agent per package over every lib/*.js file.
• Drift validation: semantic review and cross-reference review each returned confirmed-drift for both corrections. No test, example, or tooling reads either JSDoc block. The only external consumers (etc/remark/plugins/lint-html-section-structure, tools/make/lib/markdown/equations.mk) reference the package path, not the JSDoc. The new example line adds no require(, so stdlib/jsdoc-main-export still sees the self-require last, and it carries no // returns annotation for stdlib/jsdoc-doctest to check. No structural candidates reached review, so the structural-review pass had nothing to check.
• node --check passes on both files. ESLint was not run (dependencies not installed in the authoring environment).

Deliberately excluded

• remark-lint-expected-html-sections module example (var linter = remark().use( ... ) without .process): valid and minimal; judged an intentional deviation.
• Missing related README section in remark-lint-expected-html-sections and remark-lint-html-section-structure (12/14): generator-owned section.
• Concatenated lint-message strings in remark-lint-equations, remark-lint-html-section-structure, and remark-lint-expected-html-sections: these are file.message reports, not Error construction.
• remark-run-javascript-examples/lib/index.js: already touched by open PR chore: fix JavaScript lint errors (issue #10073) #15313.

Checklist

Please ensure the following tasks are completed before submitting this pull request.

• Read, understood, and followed the contributing guidelines.

AI Assistance

When authoring the changes proposed in this PR, did you use any kind of AI assistance?

• Yes
• No

If you answered "yes" above, how did you use AI assistance?

• Code generation (e.g., when writing an implementation or fixing a bug)
• Test/benchmark generation
• Documentation (including examples)
• Research and understanding

Disclosure

If you answered "yes" to using AI assistance, please provide a short disclosure indicating how you used AI assistance. This helps reviewers determine how much scrutiny to apply when reviewing your contribution. Example disclosures: "This PR was written primarily by Claude Code." or "I consulted ChatGPT to understand the codebase, but the proposed changes were fully authored manually by myself.".

This PR was produced by an automated cross-package API drift sweep run by Claude Code against @stdlib/_tools/remark/plugins. Features were extracted per package, majorities were computed at a 75% threshold, and each surviving candidate was validated by independent review passes before any edit. Both changes are mechanical JSDoc edits (3 added lines across 2 files).

---

@stdlib-js/reviewers

🤖 Generated with Claude Code

https://claude.ai/code/session_01RNGgXLihP99pK9yerPgKRr

---

Generated by Claude Code