Skip to content

Conversation

@MattDevy
Copy link
Contributor

@MattDevy MattDevy commented Nov 14, 2025

I would advise viewing this PR per-commit, as commit 2 is pretty large!


Commits:

  1. Adds the eslint rule to validate the JSDocs of endpoints
    a. Includes a fixer
  2. Runs npm run lint --prefix specification -- --fix to fix existing JSDocs that violate the rules outlined in JSDoc endpoint comments should be explicitly split in summary and description #2757

Example output:

npm run lint --prefix specification -- --fix

> specification@0.1.0 lint
> eslint --fix


/Users/mdevy/Documents/Github/elasticsearch-specification/specification/_global/bulk/BulkRequest.ts
   51:1  error  Markdown error (MD040/fenced-code-language): Fenced code blocks should have a language specified  es-spec-validator/jsdoc-endpoint-check
   90:1  error  Markdown error (MD036/no-emphasis-as-heading): Emphasis used instead of a heading                 es-spec-validator/jsdoc-endpoint-check
  102:1  error  Markdown error (MD036/no-emphasis-as-heading): Emphasis used instead of a heading                 es-spec-validator/jsdoc-endpoint-check
  107:1  error  Markdown error (MD040/fenced-code-language): Fenced code blocks should have a language specified  es-spec-validator/jsdoc-endpoint-check
  115:1  error  Markdown error (MD036/no-emphasis-as-heading): Emphasis used instead of a heading                 es-spec-validator/jsdoc-endpoint-check
  120:1  error  Markdown error (MD036/no-emphasis-as-heading): Emphasis used instead of a heading                 es-spec-validator/jsdoc-endpoint-check
  126:1  error  Markdown error (MD036/no-emphasis-as-heading): Emphasis used instead of a heading                 es-spec-validator/jsdoc-endpoint-check
  133:1  error  Markdown error (MD036/no-emphasis-as-heading): Emphasis used instead of a heading                 es-spec-validator/jsdoc-endpoint-check
  137:1  error  Markdown error (MD036/no-emphasis-as-heading): Emphasis used instead of a heading                 es-spec-validator/jsdoc-endpoint-check

/Users/mdevy/Documents/Github/elasticsearch-specification/specification/_global/create/CreateRequest.ts
  47:1  error  Markdown error (MD036/no-emphasis-as-heading): Emphasis used instead of a heading  es-spec-validator/jsdoc-endpoint-check
  67:1  error  Markdown error (MD036/no-emphasis-as-heading): Emphasis used instead of a heading  es-spec-validator/jsdoc-endpoint-check
  78:1  error  Markdown error (MD036/no-emphasis-as-heading): Emphasis used instead of a heading  es-spec-validator/jsdoc-endpoint-check
  83:1  error  Markdown error (MD036/no-emphasis-as-heading): Emphasis used instead of a heading  es-spec-validator/jsdoc-endpoint-check

/Users/mdevy/Documents/Github/elasticsearch-specification/specification/_global/delete/DeleteRequest.ts
  42:1  error  Markdown error (MD036/no-emphasis-as-heading): Emphasis used instead of a heading                 es-spec-validator/jsdoc-endpoint-check
  47:1  error  Markdown error (MD036/no-emphasis-as-heading): Emphasis used instead of a heading                 es-spec-validator/jsdoc-endpoint-check
  55:1  error  Markdown error (MD036/no-emphasis-as-heading): Emphasis used instead of a heading                 es-spec-validator/jsdoc-endpoint-check
  63:1  error  Markdown error (MD040/fenced-code-language): Fenced code blocks should have a language specified  es-spec-validator/jsdoc-endpoint-check
  70:1  error  Markdown error (MD036/no-emphasis-as-heading): Emphasis used instead of a heading                 es-spec-validator/jsdoc-endpoint-check

// ...

✖ 219 problems (219 errors, 0 warnings)
Screenshot 2025-11-14 at 15 07 52

Outstanding Questions

  1. What do we do about the existing markdown errors within the JSDocs?
  2. Which branches will need this backporting?

@github-actions
Copy link
Contributor

Following you can find the validation changes against the target branch for the APIs.

No changes detected.

You can validate these APIs yourself by using the make validate target.

@MattDevy MattDevy force-pushed the chore/jsdoc-endpoints branch from d6b8ca7 to 84997d3 Compare November 14, 2025 14:33
@MattDevy MattDevy force-pushed the chore/jsdoc-endpoints branch from 84997d3 to b3e4e66 Compare November 14, 2025 14:35
@MattDevy MattDevy marked this pull request as ready for review November 14, 2025 17:40
@MattDevy MattDevy requested review from a team as code owners November 14, 2025 17:40
@MattDevy
Copy link
Contributor Author

@pquentin given this makes changes to the docs (added spaces), does this need backporting to 9.2, 9.1 and 8.19?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants