Feature request - Doxygen stub generation

[michelleangela]

Summary:
Be able to generate Doxygen stub comments above a function.

Example:
For the function int addition(int a, int b, int c), the following stub comment will be generated above the function

/// @brief
/// @param a
/// @param b
/// @param c
/// @return
int addition(int a, int b, int c)

Generated documentation comments styles:

• Doxygen ///
• Doxygen /**
• Doxygen /*!
• Doxygen //!

This specification is in progress and may change. More details to follow on:

• Settings
• Generate stub for class or struct or other symbols?

Note: the issue tracking to display Doxygen comments on tooltips (such as from hover over a symbol) is at #658.

[cschlosser]

There is an extension that does that (and more): doxdocgen

Disclaimer: I‘m the original author so I may be biased.

Edit: Maybe we can work together on this? The problematic part is parsing the function signatures because regex is hard. If my extension could access the signature and generate information based on that it would be a lot more stable. I assume the cpptools have the information about the signature of the function similar to a clang AST?

[michelleangela]

@christophschlosser

We're going to collect telemetry from the Doxygen consumption usage on the C/C++ extension to help prioritize this feature request, as well as to help make decisions on what the overall Doxygen experience will be with the C/C++ extension (whether that requires adding features to C/C++ extension or collaborating/promoting third party tools that can fulfill this experience). The upvotes of this feature request will also be used to determine prioritization.

A few reasons we would add Doxygen generation to the C/C++ extension:

• Provide out-of-the box Doxygen consumption/generation experience to users. This could also help users discover Doxygen.
• Be feature parity with Visual Studio's Doxygen comment support for C++.

[cschlosser]

Hi @michelleangela ,

thanks for getting back to me.

adding features to C/C++ extension or collaborating/promoting third party tools

Why not both? 😉

Totally understand the reasons for integrating this into the C/C++ extension as the main reason why I wrote this extension was that VS Code was missing this feature and I transitioned from CLion, which had it, and it didn't seem close to being implemented in 2017.
If you would go forward with integrating a different solution into the C/C++ extension I hope you consider mine and the current user base so we can find a solution that benefits the developers (users) the most.

[jiefangli]

For extension version 1.12.1

Currently, the feature will be triggered via context menu command, code action (light bulb) or typing.

Context menu command:

The command will always appear regardless of the cursor position, but we mainly consider the following situations:

1. Cursor is on the line above the signature line: Only if the current line is empty and there is no comment above the current line will the comment be generated for the code item below the cursor.
2. Cursor is on the signature line: The comment will be inserted no matter if there's an empty line above the signature line.
3. Cursor is inside the body part: If the cursor is inside the function/class, and there is no other variable/function below the cursor, the comment will be generated for the parent class, and it will be inserted above the signature line of the parent class.

Except for these situations, the context menu command won't generate comments.

Code Action:

The code action (light bulb) will appear when clicking on the variable/function/class name or on the empty line above the signature line.
1) Click on the variable/function/class name: when there is no comment above the signature, the light bulb will show up to suggestion.
2) Click on the empty line above the signature line: Currently, VSCode doesn't support trigger the code action request on an empty line (microsoft/vscode#132960) so the only way to trigger the code action on an empty line requires selecting the whitespaces on the empty line. (i.e., in addition to whitespaces, there shouldn't be anything else on that line.)

Typing

Currently, there is setting doxygen.generateOnType to configure whether to insert the comment after typing the selected comment trigger string. Only when the setting is on, the comment will be generated. The four supported comment style are ///, //!. /**. /*!.

The comments will be generated when there is nothing other than the trigger string on the current line and there is no comment found above the current line.

Known Issue

As our extension do not support autocomplete for the multi-line comment (microsoft/vscode#154994), after tying /** or /*!, the comment won't be generated as the rest part of file be converted to comments.

[heartacker]

@jiefangli after type /*!

what can I do to make it work, enter?

[cschlosser]

Typing
Currently, there is setting doxygen.generateOnType to configure whether to insert the comment after typing the selected comment trigger string. Only when the setting is on, the comment will be generated. The four supported comment style are > ///, //!. /**. /*!.

Have you tested how this interacts with cschlosser.doxdocgen?

[sean-mcmanus]

@cschlosser I have not (maybe others on our team have) -- can you let us know if there is some unexpected interaction we should try to handle better. You can set "C_Cpp.doxygen.generateOnType": false to disable any unwanted interaction in the onType scenario.

[sean-mcmanus]

@heartacker Using the "C_Cpp.doxygen.generatedStyle" that start with /* doesn't currently work with the onType scenario, because it turns the code afterwards into a comment before we're able to handle it. We plan to potentially enable that to work when the */ gets auto-added after microsoft/vscode#154994 is fixed. Someone could file an issue to track that potentially.

[Spaark84]

It's great that you added support for generating doxygen comments.

Just noted a little inconsistency: When generating a Javadoc style doxygen comment that starts with /**, the indention of the final asterisk is not in line with the asterisks on the lines above it, as is normally the case.

[sean-mcmanus]

@Spaark84 The asterisk alignment is fixed with https://github.com/microsoft/vscode-cpptools/releases/tag/v1.12.2 .

[sean-mcmanus]

Fixed with https://github.com/microsoft/vscode-cpptools/releases/tag/v1.12.3 .

[gtianw]

Above is the changlog for v1.12.3.

I can't understand the meaning of auto-complete of Doxygen keywords. How to use the feature.
In other words, what's the difference between auto-complete of Doxygen keywords and Doxygen comment generation?

[sean-mcmanus]

@gtianw Auto-complete of Doxygen keywords is

whereas the comment generation itself is the /// plus any initial @ tags that get auto-generated with it based on the signature of the target type (e.g. params, return values, etc.).