TEMPLATE/REQUIRES macros hide function documentation, affect C++ tooling

XMLWordPrintableJSON

    • Server Programmability
    • ALL
    • None
    • None
    • None
    • None
    • None
    • None
    • None

      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).

        1. setwith_cxx.png
          559 kB
          Billy Donahue
        2. setwith_macros.png
          601 kB
          Billy Donahue
        3. setwith_vscode_cxx.png
          283 kB
          Billy Donahue
        4. setwith_vscode_macros.png
          259 kB
          Billy Donahue

            Assignee:
            Unassigned
            Reporter:
            Billy Donahue
            Votes:
            0 Vote for this issue
            Watchers:
            8 Start watching this issue

              Created:
              Updated: