Change doxygen comment style in Eclipse

Question

Does anyone know how to edit the style used for Doxygen comments in Eclipse CDT?

In other words type /** and pressing enter on a line before a function currently gives me something like:

/**
 * 
 * @param one
 * @param two
 * @return
 */
Foo(int one, int two);

and I want it to give me something like:

/**********************************************************************/
///
/// \param one
/// \param two
/// \return
/***********************************************************************/
Foo(int one, int two);

Also, plus one if anyone knows how to bind this to a keyboard shortcut (like alt-shift-j for Eclipse JDT).

Also, FYI, the fact that Eclipse CDT supports Doxygen now seems to be a little known fact based on Google. See here for details. Doxygen can be enabled under the project properties by selecting "Enable project specific settings" in the "C/C++ General" tab and selecting "Doxygen". My CDT version is 7.0.1, but I think this became available in 5.0.

Lastly, the comments section under code templates in preferences doesn't accomplish this based on my testing.

EDIT: See here. It seems like the comment style is hard coded. If anyone finds otherwise, I'd love to know about it. I guess templates will be the best thing for now unless the Javadoc style is okay for you.

Answer 1

Yes, this seems to be a bug in Eclipse CDT.

As a workaround I suggest you create a custom template which can be accessed with the Ctrl+Space key combination.

In Eclipse Helios: Window -> Preferences -> C/C++ -> Editor -> Templates

Click on New... to create a new template and in the Name field use some descriptive name e.g. "comment-function", and add your doxygen comment in the Pattern field. Confirm and apply this change.

In your code you can then go to the line above your function declaration, type the first few letters of your custom template name followed by the Ctrl+Space key combination.

In this example:

com<Ctrl+space>

will bring up the Content Assist dialog filtered with "com*" from which you can select the "comment-function" template.

Note:

com<Ctrl+space+space>

will filter even further by only showing Template Proposals in the Content Assist pop-up window.

Answer 2

This is a configuration I found in my java comment

and when i edited as shown my java doc comment changed to

Try to look for similar configuration under your php configuration.

Answer 3

I can get some of the way to what you want by going to: Preferences - PHP - Code Style - Code Templates - Comments.

I'm not sure that this will enable you to use backslashes instead of @s for your keywords, but I think it should achieve most of what you want.

Answer 4

Starting from eclipse 2020-03 you can use a combination of options: code template to create your header and footer using /*****/ and then in the middle just use /// customizing the style in C/C++->Editor options.

Answer 5

A Doxygen tag uses this basic format.

/**
Your tags and such. It MUST have the /** and the */.
*/

It absolutely must have the /** */ around the whole Doxygen comment. If you modify the Code Templates it will do what you want.

The proposed comment style is wrong though.

/***************/ <-- These are terminated Doxygen blocks.
/// <-- These are used in xml style Doxygen blocks.
///
/// This isn't actually a Doxygen block and shouldn't work
/// if you run Doxygen on it.
///
/***************/ <-- These are terminated Doxygen blocks.

This below is standard for most companies who code in JAVA and eclipse. Since Doxygen is valid for multiple languages this is valid for C/C++ too.

/**
 * Brief description.
 *
 * @param[in|out] <value> <description>
 */

If you want to use the xml style tags...

/// <summary>
/// This is a summary of the class, blah, blah.
/// </summary>

You're also going to want to make sure eclipse isn't inserting other comment styles too, otherwise you can end up with comments inserted inside other comments. Also generally it is a bad rule to mix comment styles like /** */ and ///.

Finally if you select auto-generate comments when you create classes and such those comments will automatically be put in. And you can have eclipse auto-generate method headers as you type (though I forget how I did this).