[SERVER-54104] TEMPLATE/REQUIRES macros hide function documentation, affect C++ tooling Created: 28/Jan/21  Updated: 06/Dec/22

Status: Open
Project: Core Server
Component/s: Internal Code
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major - P3
Reporter: Billy Donahue Assignee: Backlog - Service Architecture
Resolution: Unresolved Votes: 0
Labels: servicearch-wfbf-day
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Attachments: PNG File setwith_cxx.png     PNG File setwith_macros.png     PNG File setwith_vscode_cxx.png     PNG File setwith_vscode_macros.png    
Assigned Teams:
Service Arch
Operating System: ALL
Participants:

 Description   

The attached images show the hover-documention generated by YouCompleteMe in Vim and VSCode. Both are displaying the same data, which was produced by clangd for the Promise<T>::setWith function. The effect is much more dramatic in VSCode's rendering (screenshots attached).

The TEMPLATE()/REQUIRES() macros have disassociated the documentation above the function's declaration. Clangd treats the function as if it were undocumented, showing only a dry report of the function's metadata.

These macros do not provide a benefit in easy enable-if cases like this and should be replaced with an ordinary std::enable_if_t so they don't obscure declarations unnecessarily. After replacing TEMPLATE()/REQUIRES() with a C++ std::enable_if_t, we see a full page of documentation (screenshots attached for that condition for comparison).



 Comments   
Comment by Mathias Stearn [ 26/Jul/22 ]

I think this is a bug in clangd since it works with some macros but not others. I've reported it upstream: https://github.com/clangd/clangd/issues/1226

Generated at Thu Feb 08 05:32:40 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.