[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:

> > It's working great as intended! <img alt="image" width="295" height="455" 
> > src="https://private-user-images.githubusercontent.com/54050160/484637944-77662462-d9f8-47b8-8c7f-1ae909078ee4.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NTc5Mzg3NTIsIm5iZiI6MTc1NzkzODQ1MiwicGF0aCI6Ii81NDA1MDE2MC80ODQ2Mzc5NDQtNzc2NjI0NjItZDlmOC00N2I4LThjN2YtMWFlOTA5MDc4ZWU0LnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNTA5MTUlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjUwOTE1VDEyMTQxMlomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTdjMWVlNzBkMmIxMTAwNzMwMTQ1Yzk2ODQwYjFhYTc2YmNjYzk5ZjEzMTY3NGNiN2ZjOTU5OTVkNDEyNjY1ZTcmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0In0.eg2AVd1re94549MBMLaPMthkoMdkJ6MgNoDm0e0UMTc";>
> >  Can other commands like `@details` be added the same way we add paragraphs 
> > for `@note` and `@warning`?
> > Update: Yes we can, just add some more changes as given below. This should 
> > work well for "generic" ones that only needs a _Header_ and its content to 
> > be shown. Compiled and tested it out, working quite well.
> > ```diff
> > diff --git a/clang-tools-extra/clangd/SymbolDocumentation.cpp 
> > b/clang-tools-extra/clangd/SymbolDocumentation.cpp
> > index 86bd6162b..1638e4b55 100644
> > --- a/clang-tools-extra/clangd/SymbolDocumentation.cpp
> > +++ b/clang-tools-extra/clangd/SymbolDocumentation.cpp
> > @@ -216,6 +216,7 @@ public:
> >        break;
> >      case comments::CommandTraits::KCI_note:
> >      case comments::CommandTraits::KCI_warning:
> > +    case comments::CommandTraits::KCI_details:
> >        commandToHeadedParagraph(B);
> >        break;
> >      case comments::CommandTraits::KCI_retval: {
> > ```
> 
> I am not sure if `@details` should get a header like this. Doxygen just omits 
> this command:
> 
> ```c++
> /// @brief a sample function
> /// @note test note for myFunction
> /// @details detailed description of myFunction
> void myFunction();
> ```
> 

Personally, I am for the idea of letting `@details` have a header. 

We add doxygen support to clangd not just for "preserving the original look of 
HTML document generated by doxygen", but to improve the overall coding 
experience by providing the information acquired from the doxygen comment to 
the user. I've been using `clangd` compiled from this patch (along with header 
of `@details` added, see the diff text I gave) for two weeks, and it turns out 
that having a dedicated header for `@details` greatly improve the experience 
for me. 

Specifically, it explicitly let me know that, THIS paragraph is a brief 
(without header) which I must pay attention to, and THAT paragraph is the 
detailed description (with a header) that I may look into when I want to know 
about more details. This is very helpful when under quick development, because 
it let me acquire the MOST USEFUL information by just quickly scanning the 
hover. Without the header, it is harder to distinguish between the brief and 
the detail, especially when they are placed in the adjacent lines. And by the 
way, this is also the reason that I'm not in favor of that doxygen isn't adding 
a header for the `@details` paragraphs.

To sum up, because of the different goal and scenario
- doxygen: generate a good looking, unified documentation, potentially to be 
deployed on websites
- clangd: providing quick information (from doxygen comments) WHILE programming

I prefer adding a header for `@details`.

#### Attachment
How it look with a dedicated header for `@details`:
<img width="339" height="260" alt="image" 
src="https://github.com/user-attachments/assets/1cb768aa-72bb-40fb-9ca2-9194fd84529b";
 />
With `@notes` removed:
<img width="337" height="199" alt="image" 
src="https://github.com/user-attachments/assets/0875ef1f-df39-40ca-9358-1f464a1ecdee";
 />


https://github.com/llvm/llvm-project/pull/156365
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits