[doc-bug] Move Documentation Comments From .cpp To .hpp For Better LSP Support

[Saplyn]

When installing TFXUI using CMake's find_package(), the implementation source code is not available, resulting LSP not being able to provide correct "hover document", as they're in the implementation files, according to this stackoverflow post comment.

For instance: that "--- Widget ---" cannot be the actual document:

Here, the LSP (clangd) thinks the header file (elements.hpp) contains the documentation, but it does not:

// --- Widget ---
Element text(std::string text);

In fact, the actual documentation is written in the text.cpp:

/// @brief Display a piece of UTF8 encoded unicode text.
/// @ingroup dom
/// @see ftxui::to_wstring
///
/// ### Example
///
/// ```cpp
/// Element document = text("Hello world!");
/// ```
///
/// ### Output
///
/// ```bash
/// Hello world!
/// ```
Element text(std::string text) {
  return std::make_shared<Text>(std::move(text));
}

So... Maybe consider moving the actual documentation from implementation to declaration? As this brings better LSP support.

[ArthurSonzogni]

I would like human to be able to quickly understand headers files. Doxygen comments adds a lot of noise making it more difficult to navigate the files. A lot of FTXUI documentations adds a lot of details, examples. This is too much.

• FTXUI headers are 2792 lines.
• FTXUI doxygen documentation is 2993 lines.

Is there a way to keep the headers easily navigeable by human, while allowing machine to provide the specific details?

About your issue, it seems to be a missing feature from clangd. We should probably push in this direction instead.
I see: llvm/llvm-project#67802