microsoft / microsoft/vscode-cpptools
[Bug] No intellisense from doxygen comments placed above template function declaration with separate implementation
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 6.2k
- Forks
- 1.7k
- Avg merge
- 14h 46m
- Merged PRs (30d)
- 61
Description
Environment
- OS and Version: Any (Windows 11 10.0.22631.3593)
- VS Code Version: 1.92.2
- C/C++ Extension Version: 1.21.6
- If using SSH remote, specify OS of remote machine: N/A
Bug Summary and Steps to Reproduce
Bug Summary:
I've noticed this bug has been around probably as long as doxygen comments have been supported, and have myself worked around it, but there are inconsistencies with what doxygen uses during its own documentation generation.
I believe this is only an issue with function templates & class method templates. The short version is:
When you split up both a template declaration with its implementation, intellisense does not pick up the documentation block if it's above the declaration - only if it's above the implementation.
Steps to reproduce:
Sample code
#pragma once
namespace test
{
struct Props
{
bool flag = false;
};
// Declaration (inside header file)
// The doxygen block below needs to be here - doxygen does not
// generate the docs correctly if it's above the implementation
/**
@brief Creates a new thing
@tparam T The thing to create
@param props The properties to apply
@return T The new thing
*/
template <typename T>
[[nodiscard]] constexpr T create(Props&& props);
// Implementation (could be in a .inl file, or header file, but location doesn't matter)
template <typename T>
[[nodiscard]] constexpr T create(Props&& props)
{
return T{};
}
struct Foo
{};
void runTest()
{
auto foo = create<Foo>(Props{});
static_cast<void>(foo);
}
}
In the above example, when create is moused over (in any of the 3 places), intellisense does not show the documentation.
Expected behavior:
The documentation should show up if it is placed above the function declaration, like in the screenshot below.
Workaround:
One workaround is to not split up template declaration/implementation, but this is not ideal for me, as I prefer to separate implementations into their own files (.inl).
Another workaround is to place the doxygen block above the implementation. In doing this, intellisense does technically work (it's why I was able to get the 2nd screenshot). However, this creates its own problems:
- Doxygen requires the documentation to be above the declaration. It does not process it at all if it's only above the implementation.
- With 1 in mind: right now, you'd basically have to place the documentation in both in order for doxygen and intellisense to be happy. This is not feasible.
Configuration and Logs
c_cpp_properties.json
{
"version": 4,
"configurations": [
{
"name": "Win32",
"intelliSenseMode": "windows-msvc-x64",
"compilerPath": "C:/Program Files/Microsoft Visual Studio/2022/Community/VC/Tools/MSVC/14.39.33519/bin/HostX64/x64/cl.exe",
"cppStandard": "c++20",
"defines": [],
"forcedInclude": [],
"includePath": [
"${workspaceFolder}/src"
]
}
]
}
Other Extensions
No response
Additional context
No response
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
The standalone C++ sample and c_cpp_properties.json reproduce the split template declaration and implementation case; begin by loading that sample in VS Code with the shown configuration and comparing hover results at the three create locations. Done means the Doxygen documentation above the declaration appears in IntelliSense for the declaration, implementation, and call without duplicating the comment.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp, vscode
- Domain
- developer-experience, devtools
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100