enforce no wrapIndent for jsdoc comments #13139
Merged
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.
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.