I currently have a couple of #define in c files that turn off some functionality to hardware for testing. However, I want to document them with doxygen when they are undefined as well.
For example:
This works fine:
/// \def SIMULATE_SOME_HW_INTERFACE
/// Define this when you want to simulate HW interface.
#define SIMULATE_SOME_HW_INTERFACE
When you change the #define to #undef, you get a warning in doxygen, and it doesn't show up in the doxygen generated output. I want to document this #define wether it's defined or undefined.
How can I force doxygen to document a #undef???
Define them in a header file that is only included by Doxygen (put in a separate directory tree from the main source).
Guard this header file by wrapping it with a define that you only define in the Doxygen setup, eg:
#ifdef ONLY_FOR_DOXYGEN
/// \def SIMULATE_SOME_HW_INTERFACE
/// Define this when you want to simulate HW interface.
#define SIMULATE_SOME_HW_INTERFACE
#endif
I have used this to also conditionally include lightweight class definitions for things like MFC base classes so they appear as bases for the class hierarchy without having to parse all of MFC.
I found a kludgy way by adding the #undef under the #define. This way it's defined for Doxygen, but immediately undefined for the compiler.
/// \def SIMULATE_SOME_HW_INTERFACE
/// Define this when you want to simulate HW interface.
/// Comment out #undef to simulate HW interface
#define SIMULATE_SOME_HW_INTERFACE
#undef SIMULATE_SOME_HW_INTERFACE
I was trying to figure out how to set SIMULATE_HW_INTERFACE in the Doxyconfig file using PREDEFINED option. Couldn't get it to work. So here's my best solution so far.
I solved my problem with documenting compilerflags like this in the main headerfile:
/**
* \defgroup flags Compilerflags
*/
/**
* \def MY_FLAG
* \ingroup flags
* Dokumentation....
*/
#ifndef MY_FLAG
#define MY_FLAG
#undef MY_FLAG
#else
#define MY_FLAG
#endif
This way everything works fine: doxygen and compiling and you can keep specifying your flags in commandline...
Related
I'm compiling for an embedded target and my compiler understands some non-standard macros. I want to define some "stub" macros for the benefit of eclipse (so that it doesn't pester me with spurious warnings).
I want something like:
#ifdef ECLIPSE_ENVIRONMENT
void __WFI_STUB(void) {}
#define __WFI __WFI_STUB
#endif
So that in my code (which compiles fine),
__WFI();
Eclipse won't freak out about an unresolved function.
Ah.
#ifdef __CDT_PARSER__
// do stuff
#endif
Is it possible to tell Doxygen to expand macros but ignore other preprocessor directives?
Take the following into account:
#if defined(linux)
#define OS_LINUX
int function() { /* ... */ }
// Other functions defined for Linux
#elif defined(__WIN32__)
#define OS_WINDOWS
int function() { /* ... */ }
// Other functions defined for Windows
#else
#error "OS unsupported."
#endif
In this case, I want the functions for both Windows and Linux to show up, but I also want the macros OS_LINUX and OS_WINDOWS to show up in the documentation as well. Is there a way to document both macros while ignoring the #ifs?
No, you cannot do that you will have to build the documentation for each configuration separately. However if both Windows and Linux have the same interfaces defined, the documentation will surely be the same for both functions in any case?
By default if Doxygen finds documentation for a declaration in a header and documentation for corresponding definitions in source-files, the documentation in the header will be used. In this case you can use this to your advantage by only placing Doxygen mark-up in the header files. Normally the interfaces will be identical cross-platform and you will have a single header, but multiple implementations for each platform, either in separate sources or using conditional compilation.
I need the code I am writing for a project to match some style guidelines. However the standard templates included with CDT don't match this style. Especially the layout of the header guards is not the way it should be. I had a look at the template and for my Eclipse it looks like this:
${filecomment}
#ifndef ${include_guard_symbol}
#define ${include_guard_symbol}
${typecomment}
${declarations}
#endif /* ${include_guard_symbol} */
So I am guessing the variable ${include_guard_symbol} is set somewhere in the CDT, but is it possible to change this setting without needing to modify the CDT itself?
On a slightly different, but related note:
Is it possible to add your own templates, so you just could add new files of other types (test-cases, specialized classes etc) using the normal new dialog for the project?
We've had a similar struggle on our project. One solution is to throw out ${include_guard_symbol} in the template all together, and define it yourself, possibly using some of the other predefined variables. Something like this:
${filecomment}
#ifndef MyProject_${file_base}_h
#define MyProject_${file_base}_h
${typecomment}
${declarations}
#endif /* MyProject_${file_base}_h */
So for a header file named inc/Foo.h, the include guard would be inserted like this:
#ifndef MyProject_Foo_h
#define MyProject_Foo_h
Unfortunately, there doesn't seem to be a way to customize much beyond that. For example, if I defined a class nested in a namespace, I might want to put the namespace as part of the include guard. I can't find a way to do that in eclipse, currently.
So in the Preferences dialog under C/C++ -> Code Style -> Code Templates you can modify the template to be closer to what you need, for example if you need the namespace in the guard, you can do something like.
${filecomment}
#ifndef ${namespace_name}_${include_guard_symbol}
#define ${namespace_name}_${include_guard_symbol}
${includes}
${namespace_begin}
${declarations}
${namespace_end}
#endif /* ${namespace_name}_${include_guard_symbol} */
I'm working on a project that uses multiple libraries, set up in a structure like so:
/src
/libs/libOne
/libs/libTwo
I want to generate a single Doxygen page which covers all my code as well as the libraries. This was quite simple by just pointing Doxygen at the root. However, I want the doxygen output to be grouped so I can clearly see which library each class/file belongs to. However, since the libraries are not written by me I don't want to change them to add \addtogroup comments.
I don't mind if the produced documentation is subpar for the libraries (for example if they don't include doxy compatible comments), I still want them included so I can view call graphs, and quickly browse the classes, etc.
How can I group each libraries code into modules without changing the libraries' source?
thanks
You should put all the necessary documentation in external files. I didn't know how to do this, but I've tried to set up a minimal environment like yours and it worked well. Just for documenting something I've grabbed the example code on the Doxygen site:
test1.h:
#define MAX(a,b) (((a)>(b))?(a):(b))
typedef unsigned int UINT32;
int errno;
int open(const char *,int);
int close(int);
size_t write(int,const char *, size_t);
int read(int,char *,size_t);
and wrote the totally useless test2.h (just to have two different files...):
void itdoesnothing();
Here comes the nice part. I've made an external header just for documenting the above, called it test_doc.h (again, just used the example on the Doxygen site):
/*! \addtogroup everything The main group
This group contains everything.
#{
*/
/*! \file test.h
\brief A Documented file.
Details.
*/
/*! \def MAX(a,b)
\brief A macro that returns the maximum of \a a and \a b.
Details.
*/
/*! \var typedef unsigned int UINT32
\brief A type definition for a .
Details.
*/
/*! \addtogroup err Error handling
Error handling related stuff
#{
*/
/*! \var int errno
\brief Contains the last error code.
\warning Not thread safe!
*/
/*! #} */
/*! \addtogroup fdrelated File description related
File descriptor related stuff.
#{
*/
/*! \fn int open(const char *pathname,int flags)
\brief Opens a file descriptor.
\param pathname The name of the descriptor.
\param flags Opening flags.
*/
/*! \fn int close(int fd)
\brief Closes the file descriptor \a fd.
\param fd The descriptor to close.
*/
This successfully documented both files for Doxygen. This way you can group files, namespaces etc. too, as stated in the manual:
Members of a group can be files, namespaces, classes, functions, variables, enums, typedefs, and defines, but also other groups.
So try reading http://www.doxygen.nl/grouping.html too and see what's possible to do with the things I've mentioned above. Good luck!
I am trying to use Doxygen Automatic link generation to document some enum types. However, it is not generating links for the global enum types. It does generates links for the global struct types. Is there something I am missing? I am using the example provided on the link above. As required, I have documented the file in which the types are defined.
update1: I am using Doxygen version 1.6.3
update2: global structs are ok
Yeah, I had that same issue; i think doxygen thinks they are private or something stupid like that. Try using the \public. Don't forget to do the /*! on the first line
/*! \public
* Enum description goes here
*/
typedef enum {
/**
* Printer control language ZPL
*/
PRINTER_LANGUAGE_ZPL,
/**
* Printer control language CPCL
*/
PRINTER_LANGUAGE_CPCL
} PrinterLanguage;
I was having the same issue. Some header files generated a link for enums and other header files did not. You must explicitly document the file.
Here is a excerpt from this page int the documentation.
http://www.doxygen.nl/manual/docblocks.html#memberdoc
To document a global C function, typedef, enum or preprocessor
definition you must first document the file that contains it (usually
this will be a header file, because that file contains the information
that is exported to other source files).
Attention
Let's repeat that, because it is often overlooked: to document global objects (functions, typedefs, enum, macros, etc), you must
document the file in which they are defined. In other words, there
must at least be a
/*! \file */
or a
/** #file */
line in this file.