[clang-tools-extra] [clangd] Improve Markup Rendering (PR #140498)

[Maksim Ivanov via cfe-commits]

================
@@ -118,8 +138,8 @@ class Document {
   BulletList &addBulletList();
 
   /// Doesn't contain any trailing newlines.
-  /// We try to make the markdown human-readable, e.g. avoid extra escaping.
-  /// At least one client (coc.nvim) displays the markdown verbatim!
----------------
emaxx-google wrote:

If I understand correctly, this PR assumes that the input documentation string is written using Markdown. The current implementation in Clangd, however, is much more conservative in its assumptions - it only recognizes basic syntax features like backticks. Hence when rendering for `markdown`, everything else is escaped because the assumption is it's actually a plain text, so that all characters that'd (accidentally?) trigger special semantics in the Markdown renderer are mangled to be not treated as such:

```c++
// Tests whether C should be backslash-escaped in markdown.
<...>
// It's always safe to escape punctuation, but want minimal escaping.
// The strategy is to escape the first character of anything that might start
// a markdown grammar construct.
```

A change to pass documentation strings as-is would cause regressions on code bases where comments aren't written with the markdown syntax in mind.

P.S. As for coc-nvim - I personally don't use it, but if we're to do radical changes to how things are output, it's worth it checking we don't regress the UI for this known case.

https://github.com/llvm/llvm-project/pull/140498