[clang-tools-extra] [clangd] Doxygen Parsing: Add proper handling of \note, \warning and \retval command + change render kind of command arguments + add preprocessing for markdown code blocks/spans (PR #156365)

[Hsin-chieh Liu via cfe-commits]

Stehsaer wrote:

> Showing the `Details:` paragraph/section like in your example is intended.
> 
> The purpose is to create an own section for the detailed description, like for `Parameters` and `Return` etc. And in fact, this section is not empty. It "contains" the note command in your example.
> 
> In your example case the ruler after the `Details:` section heading is confusing maybe. But this ruler is actually part of the `@note` command. I added this ruler to try to emphasize the `@note` even more, like the markdown alerts would.
> 
> But we could also remove these rulers for the `note`, `warning` highlights to not separate it too much from the rest of the text.
> 
> Also note that the **sections** `Parameters`, `Return`, `Details` etc. are different than the **highlighting** of the `note` and `warning` commands. The highlighting is "inline" and can be used multiple times, whereas the sections are structural adaptions and unique.

This totally makes sense. Shall we make the `Details:` text a header (H5 or H6? I'm not quite sure), in order to make it bigger and separates more from other small headers like `Note:`?

---

And also, another case with unexpected behavior was found:

```cpp
///
/// @brief Some brief
///
/// @param some_param Some description
/// @retval 0 on success
/// @retval 1 Kitty asleep
///
int worker_thread(const std::string& some_param);
```
<img width="607" height="404" alt="image" src="https://github.com/user-attachments/assets/b09c9405-ca36-4a9e-9d78-a993c48642b7" />

Literally there's nothing under the `Details:` header, is there any empty line that is mistakenly parsed as a part of detail? Removing the trailing empty comment still yields the `Details:` header followed with empty content. Here are some further tests on this issue:

#### Simple comment with `@brief`
```cpp
///
/// @brief Some brief
///
int worker_thread(const std::string& some_param);
```
<img width="600" height="344" alt="image" src="https://github.com/user-attachments/assets/bc38f12b-2c7b-4d32-b269-9ae305bd98b0" />

#### Simple comment without `@brief`
```cpp
///
/// Some brief
///
int worker_thread(const std::string& some_param);
```
<img width="606" height="300" alt="image" src="https://github.com/user-attachments/assets/27f0daf3-ca05-42e9-b32b-2d174d3722b6" />

#### Original case without `@brief`
```cpp
///
/// Some brief
///
/// @param some_param Some description
/// @retval 0 on success
/// @retval 1 Kitty asleep
///
int worker_thread(const std::string& some_param);
```
<img width="608" height="407" alt="image" src="https://github.com/user-attachments/assets/c194394e-4800-4ce4-8b2b-74d169402174" />


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