microsoft / microsoft/vscode-cpptools

[Bug] No intellisense from doxygen comments placed above template function declaration with separate implementation

Open
#12,614 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug Feature: Doc comments Language Service
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.

intellisense_bug1

Expected behavior:

The documentation should show up if it is placed above the function declaration, like in the screenshot below.

intellisense_bug2

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:

  1. Doxygen requires the documentation to be above the declaration. It does not process it at all if it's only above the implementation.
  2. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.