2

I'm documenting C code with doxygen. To make the documentation more readable I want to at least add code in every .c/.h file pair to one group using @defgroup and @ingroup. Inside these groups I want to group some defines together using @name blocks.

The result in the "file" pages looks closely to what I expected: Everything that's documented in the file is listed there and more or less nicely grouped. In the "module" pages on the other hand only functions and variables are listed and the defines before the first @name block are listed under "variables". All other defines and enums are missing. Removing the @name blocks lists all defines/typedefs/enums under "variables". No own sections for macros or enums and no further grouping on these pages.

How do I get all defines and enums in a group listed on the module/group page like on the file pages where the defines/functions etc. are documented?

I use doxygen 1.8.9.1 windows binarires.

My code looks similar to this: .h file:

/** @file
*   blabla
*   @author bla
*/
/// @ingroup MY_GRP
/// @{
#define SOMEDEF1 1
/// @name Special defs
/// @{
#define SOMEDEF2 2
/// @}
enum someenum {
foo,
bar
};

extern int some_variables;

extern void some_proc(int baz);

/// @}

.c file looks like this:

/** @file
 *  blabla
 *  @author bla
 */
/** @defgroup MY_GRP A test group.
  * Description
  */
/// @{
#include "my.h"

/// Important variable.
int some_variable;

/** Important proc
 *  Description
 *  @param baz need this
 */
void some_proc(int baz) {
// code
}

/// @}

I let doxygen wizzard generate a doxyfile and also generated a DoxygenLayout.xml file. When playing arround with the layout file I found that the "defines" tags on the group pages are empty (they apparently do nothing) while the "defines" in the variables section are generated by a "membergroups" tag... Don't know what to make of this.

Any help is much appreciated. If you need the doxyfile or anything else let me know.

Bytemaster
  • 83
  • 1
  • 9
  • See if using addtogroup at the file level doesn't do what you are looking for http://stackoverflow.com/a/22461669/2344440 – Nick Jan 08 '15 at 13:20
  • Just to be clear, are you wanting undocumented entities to be grouped too? If so you need to go into the config file or advanced config in the GUI and look for an item named "extract undocumented entities". That will need to be enabled. – Nick Jan 08 '15 at 13:23
  • addtogroup instead of ingroup seems to do the trick - no clue why though. Need to do more tests... And no: I'd be happy if doxygen would group just documented entities. Up until now it didn't even do that right. – Bytemaster Jan 08 '15 at 14:32
  • Well, almoust there! Variables declared in the header and implemented in the c file are now listed twice in the group page. How do I get rid of the doubles? – Bytemaster Jan 08 '15 at 15:16
  • If you document a declaration in a header and then document a definition in the C file, generally doxygen will try to merge the documentation for both of these because both pertain to the same object at the end of the day. When you say declared in the header, do you mean using extern? Are you sure you are declaring them and not accidentally defining them? Because if you have two definitions with different scopes doxygen will generate duplicate documentation. But you should get a linker error if you define something in a header and at the file scope in a C file that includes that header. – Nick Jan 08 '15 at 16:25
  • I looked back at your OP and do see the `extern int some_variables` and I am assuming that is representative of what you are referring to. – Nick Jan 08 '15 at 16:29
  • New thought, can you post a separate question about the documentation for elements declared via extern being duplicated. That will make things easier to follow. Then we can close this thread as a duplicate to the question I asked a year ago. – Nick Jan 08 '15 at 16:32
  • possible duplicate of [Doxygen: Can file members inherit a module grouping if they are in a file that is grouped?](http://stackoverflow.com/questions/22414328/doxygen-can-file-members-inherit-a-module-grouping-if-they-are-in-a-file-that-i) – Nick Jan 08 '15 at 16:36
  • First: Thanks for bearing with me and this annoying issue. Then: Your guess is right. The snipped is representative and I always declare variables and functions with ´extern´ in header files (fixed that part in the OP). I'll post a new question about this duplicate issue in a minute. – Bytemaster Jan 08 '15 at 16:40

1 Answers1

0

Adding all members of a file to a group can be accomplished using the @addtogroup tag.

The same question is already answered here: Doxygen: Can file members inherit a module grouping if they are in a file that is grouped?

albert
  • 8,285
  • 3
  • 19
  • 32
Nick
  • 1,361
  • 1
  • 14
  • 42
  • 1
    This solution leaves open a problem - variable documentation is doubled. See [C and doxygen - removing duplicates of variable documentation](http://stackoverflow.com/questions/27845542/c-and-doxygen-removing-duplicates-of-variable-documentation) – Bytemaster Jan 08 '15 at 17:03