Hello prettier-plugin-jsdoc devs! Thank you very much for all the hard work on this great tool. Our team is beginning to use it, and we encountered an issue that is partially with prettier itself and potentially arguably partially with this plugin.
We are facing an issue with prettier not properly detecting git merge conflict markers in multi-line comments which leads to the document being formatted and prettier-plugin-jsdoc disabling merge conflict markers in JSDoc comments. It seems that, when a git merge conflict marker is in a file, prettier throws and logs Error formatting document. and Merge conflict marker encountered. instead of formatting the file. Example (Playground link):
<<<<<<< HEAD:file.txt
Things
=======
Stuff
>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
As such, prettier-plugin-jsdoc doesn't format anything in the document. However, prettier does not detect git merge conflict markers within a multi-line comment and successfully formats the document (Playground link).
This means that, if a file has merge conflicts within a JSDoc, prettier-plugin-jsdoc formats that JSDoc and disables the merge conflict markers like so:
Input:
/**
* This line doesn't need to be here, but it illustrates the issue
<<<<<<< HEAD:file.txt
* Other things in comment
=======
* Other stuff in comment
>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
* This line also doesn't need to be here, but it illustrates the issue
*/
Output:
/**
* # This line doesn't need to be here, but it illustrates the issue
* <<<<<<< HEAD:file.txt
* Other things in comment
*
* Other stuff in comment> > > > > > > 77976da35a11db4580b80ae27e8d65caf5208086:file.txt This line also doesn't need to be here, but it
* > > > > > > > illustrates the issue
*/
Expected behavior:
In the first place, I expect that Prettier would detect git merge conflict markers anywhere in a document including within multi-line comments, throws and logs Error formatting document. and Merge conflict marker encountered., and does not format the document. (Issue filed with them at https://github.com/prettier/prettier/issues/15613).
Update: Prettier closed the issue, saying these comments are valid JS comments. I think that makes enough sense. As such, I suppose this would be something you would want to make sure to preserve in this plugin since you're editing certain JS comments. I edited the following paragraph accordingly.
I expect that prettier-plugin-jsdoc would not format a JSDoc with merge conflicts in it because it disables the merge conflicts, meaning it would be easy to miss this and commit this messy JSDoc. Since Prettier ignores all JS comments but this plugin modifies certain comments, this plugin should detect when merge conflict markers are present in the JSDoc comments and preserve them accordingly.
hosseinmd
commented
10 months ago
Hello
prettier-plugin-jsdocdevs! Thank you very much for all the hard work on this great tool. Our team is beginning to use it, and we encountered an issue that is partially with prettier itself and potentially arguably partially with this plugin.We are facing an issue with prettier not properly detecting git merge conflict markers in multi-line comments which leads to the document being formatted and
prettier-plugin-jsdocdisabling merge conflict markers in JSDoc comments. It seems that, when a git merge conflict marker is in a file, prettier throws and logsError formatting document.andMerge conflict marker encountered.instead of formatting the file. Example (Playground link):As such,
prettier-plugin-jsdocdoesn't format anything in the document. However, prettier does not detect git merge conflict markers within a multi-line comment and successfully formats the document (Playground link).This means that, if a file has merge conflicts within a JSDoc,
prettier-plugin-jsdocformats that JSDoc and disables the merge conflict markers like so:Input:
Output:
Expected behavior: In the first place, I expect that Prettier would detect git merge conflict markers anywhere in a document including within multi-line comments, throws and logs
Error formatting document.andMerge conflict marker encountered., and does not format the document. (Issue filed with them at https://github.com/prettier/prettier/issues/15613).I expect that
prettier-plugin-jsdocwould not format a JSDoc with merge conflicts in it because it disables the merge conflicts, meaning it would be easy to miss this and commit this messy JSDoc. Since Prettier ignores all JS comments but this plugin modifies certain comments, this plugin should detect when merge conflict markers are present in the JSDoc comments and preserve them accordingly.Thank you again very much!