-
Notifications
You must be signed in to change notification settings - Fork 2.2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
enforce no wrapIndent for jsdoc comments #13139
Conversation
@@ -161,7 +162,7 @@ | |||
"matchingFileName": "src/fake_filename_for_jsdoc_examples", | |||
"rejectExampleCodeRegex": "<script>" | |||
}], | |||
"jsdoc/check-line-alignment": ["error", "any", {"wrapIndent": " "}], | |||
"jsdoc/check-line-alignment": ["error"], |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should we enforce wrapIndent
with an empty string instead? So we always catch broken indent.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
According to the README, the default for wrapIndent
is the empty string. https://github.com/gajus/eslint-plugin-jsdoc/blob/HEAD/docs/rules/check-line-alignment.md#wrapindent
03207af
to
3396c50
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good to me apart from 2 lint failures — let's get the build green before merging.
3396c50
to
3b9d5ee
Compare
@mourner checks are passing, can you merge when ready? |
This PR addresses an issue that caused incorrect rendering of generated documentation on docs.mapbox.com.
The JSDoc comments for some parameters span multiple lines, and indentation of lines is enforced by the
jsdoc/check-line-alignment
eslint rule. This repo has additional configuration to force an indentation of 4 spaces on wrapped lines.This indentation of subsequent lines results in markdown parsing issues. For example, the markdown to be parsed for Map.options.style looks like:
The first three lines are parsed as a paragraph, but the lines after the empty line are parsed as a codeblock, and renders as such on docs.mapbox.com:
This PR removes the
wrapIndent
option, enforcing no indentation on wrapped lines. The resulting JSDoc comments were tested locally withmapbox-gl-js-docs
and result in correct rendering in the docs:I am not clear on the repercussions of this change to other things that make use of the JSDoc comments, if any, and seek guidance from others with more experience with this codebase on whether this change is safe.
Launch Checklist
@mapbox/map-design-team
@mapbox/static-apis
if this PR includes style spec API or visual changes.@mapbox/gl-native
if this PR includes shader changes or needs a native port.