Documents displayed in hover do not retain line breaks #95
Comments
|
Using coc.nvim with neovim I have a slightly different issue - there is no space between "Declared in" and " Possibly from this line of code?: https://github.com/llvm-mirror/clang-tools-extra/blob/480d1d002ab582d82d996ea0909ab07e068d2fbb/clangd/XRefs.cpp#L1276 |
|
Thanks for reporting this! Fixing the multi-line issue should be easy enough in our code that renders the markdown strings. I'll take a look. @smhc, for the coc.nvim issue - it's true that we probably don't add a space between the text and the inline block, but most markdown renderers seem to add it anyway. |
|
Looking at how GitHub renders the corresponding markdown block, we should probably add a space too: The space does make a difference and the version with a space looks nicer. |
|
A fix for the missing space in coc.nvim is under review: https://reviews.llvm.org/D66086 |
|
Preserving line breaks: https://reviews.llvm.org/D66087 |
|
Regarding newlines: It's not clear that preserving them is an improvement overall. If the code looks like this:
then preserving line breaks in the markdown will often result in rendering like this:
(which probably looks familiar to anyone who deals with mailing lists a lot...) Comments tend to be a mish-mash of paragraphs, code examples, bulleted lists, and other structure (like doxygen-ish comments). My guess is that paragraphs are generally more common than structure, and merging structure does more damage than failing to merge paragraphs. i.e. simply preserving all breaks will make a few cases much better and most cases slightly worse. I'm not sure that's actually an improvement. We can improve on this by using heuristics to understand what's likely, such as:
Patches welcome-ish - I think we actually need some design here first. Ilya points out we're in no-man's-land at the moment: we don't strip the newlines when rendering as plaintext, but we don't preserve them in markdown. Though there's some virtue here too: plaintext clients are going to tend towards using a code font, and preserving newlines is relatively more useful when the font is monospace (as it does a better job of preserving structure). (The missing space is uncontroversial I think) |
Summary: This results in better rendering of resulting markdown. Especially noticeable in coc.nvim that does not have a visible horizontal spaces around inline code blocks. More details and a screenshot from coc.nvim can be found in clangd/clangd#95. Reviewers: sammccall Reviewed By: sammccall Subscribers: MaskRay, jkorous, arphaman, kadircet, cfe-commits Tags: #clang Differential Revision: https://reviews.llvm.org/D66086 git-svn-id: https://llvm.org/svn/llvm-project/clang-tools-extra/trunk@368581 91177308-0d34-0410-b5e6-96231b3b80d8
Summary: This results in better rendering of resulting markdown. Especially noticeable in coc.nvim that does not have a visible horizontal spaces around inline code blocks. More details and a screenshot from coc.nvim can be found in clangd/clangd#95. Reviewers: sammccall Reviewed By: sammccall Subscribers: MaskRay, jkorous, arphaman, kadircet, cfe-commits Tags: #clang Differential Revision: https://reviews.llvm.org/D66086 llvm-svn: 368581
Summary: This results in better rendering of resulting markdown. Especially noticeable in coc.nvim that does not have a visible horizontal spaces around inline code blocks. More details and a screenshot from coc.nvim can be found in clangd/clangd#95. Reviewers: sammccall Reviewed By: sammccall Subscribers: MaskRay, jkorous, arphaman, kadircet, cfe-commits Tags: #clang Differential Revision: https://reviews.llvm.org/D66086
Summary: This results in better rendering of resulting markdown. Especially noticeable in coc.nvim that does not have a visible horizontal spaces around inline code blocks. More details and a screenshot from coc.nvim can be found in clangd/clangd#95. Reviewers: sammccall Reviewed By: sammccall Subscribers: MaskRay, jkorous, arphaman, kadircet, cfe-commits Tags: #clang Differential Revision: https://reviews.llvm.org/D66086
------------------------------------------------------------------------ r368581 | ibiryukov | 2019-08-12 16:35:30 +0200 (Mon, 12 Aug 2019) | 18 lines [clangd] Separate chunks with a space when rendering markdown Summary: This results in better rendering of resulting markdown. Especially noticeable in coc.nvim that does not have a visible horizontal spaces around inline code blocks. More details and a screenshot from coc.nvim can be found in clangd/clangd#95. Reviewers: sammccall Reviewed By: sammccall Subscribers: MaskRay, jkorous, arphaman, kadircet, cfe-commits Tags: #clang Differential Revision: https://reviews.llvm.org/D66086 ------------------------------------------------------------------------ llvm-svn: 368670
------------------------------------------------------------------------ r368581 | ibiryukov | 2019-08-12 16:35:30 +0200 (Mon, 12 Aug 2019) | 18 lines [clangd] Separate chunks with a space when rendering markdown Summary: This results in better rendering of resulting markdown. Especially noticeable in coc.nvim that does not have a visible horizontal spaces around inline code blocks. More details and a screenshot from coc.nvim can be found in clangd/clangd#95. Reviewers: sammccall Reviewed By: sammccall Subscribers: MaskRay, jkorous, arphaman, kadircet, cfe-commits Tags: #clang Differential Revision: https://reviews.llvm.org/D66086 ------------------------------------------------------------------------ git-svn-id: https://llvm.org/svn/llvm-project/clang-tools-extra/branches/release_90@368670 91177308-0d34-0410-b5e6-96231b3b80d8
|
note that new rendering behavior strips newlines in plaintext mode too. |
|
We talked about heuristics to detect line breaks in the past, telling the difference between a soft-wrap and a hard-wrap isn't trivial but usually possible (punctuation, is the line shorter than the longest line, etc). A maybe-simpler alternative/fallback: detect when the documentation has "interesting formatting" and render the whole thing as a verbatim code block. Regarding the example, detecting the comment is markdown and preserving it is interesting but also challenging. I don't know that markdown comments are all that common but I kind of wish they were, and it's partly from lack of tooling. Maybe we should be the change we want to see... |
`parseDocumentation` retains hard line breaks and removes soft line breaks inside documentation comments. Wether a line break is hard or soft is determined by the following rules (some of which have been discussed in clangd/clangd#95): Line breaks that are preceded by a punctuation are retained Line breaks that are followed by "interesting characters" (e.g. Markdown syntax, doxygen commands) are retained All other line breaks are removed Related issue: clangd/clangd#95 Differential Revision: https://reviews.llvm.org/D76094
`parseDocumentation` retains hard line breaks and removes soft line breaks inside documentation comments. Wether a line break is hard or soft is determined by the following rules (some of which have been discussed in clangd/clangd#95): Line breaks that are preceded by a punctuation are retained Line breaks that are followed by "interesting characters" (e.g. Markdown syntax, doxygen commands) are retained All other line breaks are removed Related issue: clangd/clangd#95 Differential Revision: https://reviews.llvm.org/D76094
Summary: This results in better rendering of resulting markdown. Especially noticeable in coc.nvim that does not have a visible horizontal spaces around inline code blocks. More details and a screenshot from coc.nvim can be found in clangd/clangd#95. Reviewers: sammccall Reviewed By: sammccall Subscribers: MaskRay, jkorous, arphaman, kadircet, cfe-commits Tags: #clang Differential Revision: https://reviews.llvm.org/D66086 llvm-svn: 368581


The text was updated successfully, but these errors were encountered: