30

I'm using Eclipse CDT to write C++ code. Having read several discussions here on StackOverflow about whether to place doxygen documentation in the header file or the implementation file, it seems the majority of developers favour putting doxygen comments in the header file (although it's by no means a consensus, of course). However, if I put doxygen comments in my header files, I can't get Eclipse to display those comments when I hover the mouse pointer over an instance of the commented method/member. Is there a way to get Eclipse to make use of my Doxygen documentation from my header files in Eclipse's hover tips?

I've set "Documentation tool comments Workspace default" to "Doxygen" in Preferences > C/C++ > Editor.

I'm using Eclipse 3.6.2 with CDT 7.0.2 on Ubuntu 11.04.

Jack Kelly
  • 2,214
  • 2
  • 22
  • 32
  • 3
    I stumbled over the same problem. Eclipse CDT can display documentation from the header files without problems as long as it has no access to the implementation source because then it prefers to display the documentation from there (even if there is none). Really annoying. – kayahr Jul 13 '14 at 12:38

2 Answers2

2

Doxygen comments are displayed in Eclipse on hover when written in:

  • cpp file (or header) file before method source (not declaration)
  • header file before class declaration
Yuriy Petrovskiy
  • 7,888
  • 10
  • 30
  • 34
  • 6
    Yeah, your answer is consistent with what I've found too. Do you know if there are any ways to get Eclipse to display Doxygen comments from the header file for methods and member variables? – Jack Kelly Jul 14 '11 at 12:31
  • 1
    Actually I see no sense for that. I think it is the best places to describe code because you can see what you describe only in this cases. Comments in header files are only useful when writing/using libraries. – Yuriy Petrovskiy Jul 15 '11 at 21:38
  • 8
    @Yuriy Petrovskiy description in header is much more useful, since you shouldn't look at the implementation code, only at the interface in the header – avim Mar 29 '15 at 15:09
  • 2
    Agree with @avim in general. In addition, I am writing a library so the only sensible place to put the comments is in the header. The source will not go to the client but the header will. – Brick Jun 27 '17 at 17:12
  • This is rather unfortunate as the hover should be used by callers to find out explanations on how to use the function not how it's implemented. I would never hover to find information on how the function is implemented, I would go to the definition for that. – David Bradley Feb 13 '22 at 15:48
1

I found a workaround for this problem, however it's pretty inconvenient for general use.

If you're using an external build system (make/cmake eg.) where eclipse is unable to pass on it's macro definitions, then all you need to do is place the implementation in it's own include guard and add the include guards macro to eclipse's symbol definitions. This will hide that section of code from eclipse, forcing it to use the intended comments without affecting the build.

For example:

#ifndef INCLUDE_GUARD_FOR_IMPLEMENTATION
#define INCLUDE_GUARD_FOR_IMPLEMENTATION

// Implementation code

#endif

and then in project -> properties -> C/C++ General -> Paths And Symbols add INCLUDE_GUARD_FOR_IMPLEMENTATION under the symbols section.

It does of course have the side effect of greying out the section, and if you can't or don't want to put the implementation code in a separate header it might look rather out of place.

NotVeryMoe
  • 544
  • 5
  • 9