Doxygen misrendering macro type as a public member function
I am using a type macro list(type)
that expands to dynamic type [ list_of_type
] as shown below:
main snippet
...
#define list(type) force_append_macro(list_of_,type)
...
typedef struct _improperlydocumented
{
list(char_ptr) *words;
}improperlydocumented;
...
Problem
doxygen incorrectly renders this type [
list(char_ptr)
] as a public member function (instead of member data).
environmental information
$ lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Description: Ubuntu 14.04.1 LTS
Release: 14.04
Codename: trusty
$ doxygen --version
1.8.6
doxygen wizard generates the following output:
my code / config:
doxygen.config
PROJECT_NAME = "doxytest"
OUTPUT_DIRECTORY = ./build/docs
OPTIMIZE_OUTPUT_FOR_C = YES
TYPEDEF_HIDES_STRUCT = YES
HIDE_SCOPE_NAMES = YES
SHOW_NAMESPACES = NO
INPUT = ./
FILE_PATTERNS = *.h *.c
GENERATE_HTML = YES
GENERATE_LATEX = NO
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = NO
EXPAND_ONLY_PREDEF = YES
SEARCH_INCLUDES = YES
INCLUDE_PATH =
INCLUDE_FILE_PATTERNS =
PREDEFINED =
EXPAND_AS_DEFINED =
Note: I tried the installation EXPAND_AS_DEFINED = list
; with the same output as below.
list.h
#ifndef __list__
#define __list__
typedef struct
{
int capacity,
count,
objsize,
xprate;
void *data;
}glist_t;
/* allow list types to be defined (as wrappers around generic_list) */
#define append_macro(a,b) a ## b
#define force_append_macro(a,b) append_macro(a,b)
#define declare_named_list_type(name,type) typedef union\
{struct force_append_macro(_template_,name)\
{\
int capacity,\
count,\
objsize,\
xprate;\
type *data;\
}template;\
glist_t ls;\
}name
#define declare_list_type(type) declare_named_list_type(force_append_macro(list_of_,type),type)
#define list(type) force_append_macro(list_of_,type)
typedef char * char_ptr;
declare_list_type(char_ptr);
/*!
* This object is improperly documented.
*
* Issue is that the list(char_ptr) is treated as a member function instead of a type..
*/
typedef struct _improperlydocumented
{
list(char_ptr) *words;
}improperlydocumented;
#endif
doxygen output
incorrectly documented construct reference
#include
Public functions of members
list (char_ptr)*words
Detailed description
This object is not properly documented.
The problem is that the list (char_ptr) is treated as a member function instead of a type ..
Question
How can I fix doxygen output for a document words
as element data (not a public member function)?
configuration attempts
PROJECT_NAME = "doxytest"
OUTPUT_DIRECTORY = ./build/docs
OPTIMIZE_OUTPUT_FOR_C = YES
TYPEDEF_HIDES_STRUCT = YES
HIDE_SCOPE_NAMES = YES
SHOW_NAMESPACES = NO
INPUT = ./
FILE_PATTERNS = *.h *.c
GENERATE_HTML = YES
GENERATE_LATEX = NO
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES|NO **
SEARCH_INCLUDES = YES
INCLUDE_PATH =
INCLUDE_FILE_PATTERNS =
PREDEFINED =
EXPAND_AS_DEFINED = list
** tried both YES and NO with all other settings the same (asterisks not included;)
PROJECT_NAME = "doxytest"
OUTPUT_DIRECTORY = ./
OPTIMIZE_OUTPUT_FOR_C = YES
TYPEDEF_HIDES_STRUCT = YES
HIDE_SCOPE_NAMES = YES
SHOW_NAMESPACES = NO
INPUT = ./
FILE_PATTERNS = *.h *.c
GENERATE_HTML = YES
GENERATE_LATEX = NO
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = NO
SEARCH_INCLUDES = YES
INCLUDE_PATH =
INCLUDE_FILE_PATTERNS =
PREDEFINED =
still doesn't expand the list (char_ptr) as expected. without changing the output
I tried to replicate a working script (discussed below) to windows, copy + paste above the config and list.h files:
source to share
From Doxygen documentation
EXPAND_ONLY_PREDEF
If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are set to YES, then the macro expansion is limited to macros specified using the PREDEFINED and EXPAND_AS_DEFINED tags.
Default value: NO.
This tag requires the ENABLE_PREPROCESSING tag to be set to YES.
EXPAND_AS_DEFINED
If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES, this tag can be used to specify a list of macro names to be expanded. A macro definition found in sources will be used. Use the PREDEFINED tag when you want to use a different macro definition that overrides the definition found in the source code.
This tag requires the ENABLE_PREPROCESSING tag to be set to YES.
Thus, the EXPAND_AS_DEFINED option will only work if the MACRO_EXPANSION parameter is specified as yes
(which it is not).
So just specify MACRO_EXPANSION
how yes
and add list
to EXPAND_AS_DEFINED
. This will fix your problem.
EDIT
The following configuration (only relevant options) has been tested with Doxygen 1.8.5, 1.8.6 and 1.8.9.1 (under Win7):
PROJECT_NAME = "doxytest"
OUTPUT_DIRECTORY = ./
OPTIMIZE_OUTPUT_FOR_C = YES
TYPEDEF_HIDES_STRUCT = YES
HIDE_SCOPE_NAMES = YES
SHOW_NAMESPACES = NO
INPUT = ./
FILE_PATTERNS = *.h *.c
GENERATE_HTML = YES
GENERATE_LATEX = NO
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = NO
SEARCH_INCLUDES = YES
INCLUDE_PATH =
INCLUDE_FILE_PATTERNS =
PREDEFINED =
The rest of the parameters are left by default.
Generated output:
incorrectly documented construct reference
#include <list.h>
Public functions of members
list_of_char_ptr* words
Detailed description
This object is not properly documented.
The problem is that the list (char_ptr) is treated as a member function instead of a type ..
source to share