If have code in the following format:
#ifdef MY_DEFINE
///some doxy comment
#else
///other doxy comment
#endif
MY_DEFINE is defined at compile time. My issue is that when doxy processes the code above, only "other doxy comment" is handled. Defining MY_DEFINE in the doxyfile makes it so "some doxy comment" is handled. I need both doxy comments to make it into the doxygen output.
Is there a simple catch all configuration I can add to the doxyfile?
The doxygen generation needs to be run on different machines, so something not needing additional installation is preferred. There are other #define statements which need to be handled by doxygen, so setting ENABLE_PREPROCESSING to NO is not enough.
Thanks!
You can set ENABLE_PREPROCESSING=YES, then add a predefined symbol PREDEFINED=DOXYGEN
Then you can:
#if defined(MY_DEFINE) || defined(DOXYGEN)
/// if defined
#endif
#if !defined(MY_DEFINE) || defined(DOXYGEN)
/// if not defined
#endif
The drawback is that you cannot use #else. Also Doxygen gets confused if the same symbol is defined to be two different things on different preprocessor settings.
If you disable ENABLE_PREPROCESSING you cannot document #define's in your headers.
Related
Have my own macro defined in myProject.pch file,
For example:
#define Enable_Analytics
And i want to enclose few statements of code at multiple places inside
#ifdef Enable_Analytics
// Code statements which has to executed only if Enable_Analytics is defined
#endif
This is useful to include/remove code based on the macro.
In Objective-C this works but in swift i get error. How to use #ifdef in swift?
You can call the C preprocessor on just about and kind of file even if it is not C or a C like language.
It is usually available as cpp on most Unix like systems. Just run cpp your-file.swift and the C preprocessor should preprocess the file just as it would C.
However I do not know of a way to make the preprocessor use defines within a project file. So you probably will have to manually specify them on the command line like -DMACRO_NAME=somevalue.
Alternatively you could #include a file containing the defines within each of your swift files and the preprocessor will insert them.
I have a library that has several options defined as this:
#define shouldShowToolbar YES
#define shouldAlignToLeft YES
etc..
and I'm looking for a way to actually replace those from outside (without modifying the library, because the future updates will break it). Is it possible, or am I doomed to change the library source code (which I do have) every time an update comes out.
There is #undef
#include "library_header.h" /* Which defines the macro. */
#undef shouldShowToolbar /* You undef it. */
#define shouldShowToolbar NO /* If you want, you can redefine it. */
http://gcc.gnu.org/onlinedocs/cpp/Undefining-and-Redefining-Macros.html
If you don't want a particular macro to take effect for a section of code and you know that macro name too, you can use
#undef shouldShowToolbar
/* Your code */
#define shouldShowToolbar
This wont totally undef the macro, cos you never know which part of your code might actually want it
These are values that are hardcoded at compile time. If you compile the library with your project then you should be able to redefine them in a file that compiles later in the compile list, I think there is a special keyword for it. Otherwise it is like saying I want to replace YES in the library.
As far as i know, preprocessor directives executes before compilation. So after that, there's no chance to change something.
I've just installed and setup an instance of Doxygen, but out of the box it only finds TODO tags in code when marked in a block like:
/**
* #todo Foo
*/
It doesn't seem to find:
// TODO Foo
// FIXME Bar
// #todo Baz
Most IDE's and bug trackers which handle parsing are fine with them, is there an easy way to configure Doxygen to find them and list them as ToDo items?
There are a number of examples and methods we can use:
For a one line comment with valid doxygen commands (e.g. \todo) you would use
/// \todo Some (optional) text
Note the three forward slashes, not the usual two. See point three on the second list in the special documentation blocks section of the doxygen documentation. This can be used to add new todo items to your source code.
Generally one can define custom tags (like FIXME) by defining an alias in the Doxygen configuration file. For example
ALIASES += FIXME="\todo"
which will allow you to write \FIXME in your source code and the comments prefixed with \FIXME will be included in you todo list in the final documentation. The problem here is that you have to prefix your aliases with the \ (or #) symbol and begin the comment with three leading forward slashes which, if you want to leave the FIXMEs in your code as they are, is not an option.
Finally, an alternative method, and what I think you are looking for, would be to preprocess your source files using the INPUT_FILTER configuration file option. This option defines a command that is applied to each of your source files before doxygen builds the documentation, so we can define a command which replaces instances of TODO and FIXME with valid doxygen markup.
INPUT_FILTER = "sed -e 's/\/\/.*FIXME/\/\/\/ \\todo/'"
This filter replaces all instances of // FIXME (with any amount (or none) of whitespace between // and FIXME) with /// \todo. This substitution is made internally by doxygen only: your source files are not modified on disk.
Note: This last point was inspired by the accepted answer to the question Getting doxygen and MSVC TODO tags to work together. However, that answer used the FILE_VERSION_FILTER configuration option rather than INPUT_FILTER. I think that the latter (INPUT_FILTER) is actually more appropriate here. Also, the sed command used in that answer does not work for me.
Apart from the PREDEFINED configuration option, where I could always put DOXYGEN=1, does doxygen predefine any preprocessor macros prior to reading C++ files?
My train of thought is that GCC predefines macros such as __GNUC__, and MSC predefines macros such as _MSC_VER. Does doxygen predefine macros at all, such as _DOXYGEN_VER?
I don't want to use the PREDEFINED configuration option at all.
No, Doxygen does not predefine any self-identifying tokens.
If you don't want to litter your code with preprocessor #ifdef _DOXYGEN_VER / #endif blocks you can use the \cond command. The \cond command is an easier way to define sections that may be conditionally included/excluded similar to what you used to have to do with the C preprocessor tokens.
I'm a relative beginner with doxygen, and am documenting a C program
Part of the code is:
\#include "options.h"
// options.h contains
\#define VAL0 0 // Possible values for PARAM
\#define VAL1 1
\#define PARAM VAL0
// Here's the conditional compilation
\#if (PARAM == VAL0)
// code chunk, which doesn't get compiled by Doxygen
\#endif
The code compiles with GCC as expected, but I get no Doxygen documentation
OK, Doxygen doesn't expand macros, so I tried:
\#define SYMEQ(A, B) (A == B) ? 1 : 0
\#if SYMEQ(PARAM, VAL0)
// code chunk
\#endif
Set the Doxygen:
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
No Predefined macros
EXPAND_AS_DEFINED = SYMEQ
No doxygen output from the conditional part, just up to it
I also tried EXPAND_AS_DEFINED SYMEQ(A, B)
Also no luck
I found a few examples with simple names, then #ifdef NAME \code #endif, but none with macro functions
I just had the problem #ifdef CONDITION \code not compiled by doxygen\ #endif and fixed it by brute force, i.e, appending the conditions to the setting PREDEFINED=CONDITION1 CONDITION2 ... manually.
I tried the header file solution -- generate a file with conditions and include it by setting SEARCH_INCLUDES, INCLUDE_PATH and INCLUDE_FILE_PATTERNS -- but it did not work. From the doxygen manual, I think it requires to explicitly #include "the condition file" in the source files, which means to modify the source code, so I give up.
SEARCH_INCLUDES:
If the SEARCH_INCLUDES tag is set to YES (the default) the includes files in the INCLUDE_PATH (see below) will be searched if a #include is found.
MACRO_EXPANSION and EXPAND_ONLY_PREDEF only control whether a macro will be expanded in your code, not how it will be evaluated in conditional preprocessor blocks. For example, if you had code like:
#define RET_TYPE int
/**
* Some function
*/
RET_TYPE func(void);
With MACRO_EXPANSION=NO, this will be documented by doxygen as RET_TYPE func(void), the macro isn't expanded. With MACRO_EXPANSION=YES, this will be documented as int func(void), the macro is expanded and the resulting signature is documented.
To control conditional code, you'll want to focus on the ENABLE_PREPROCESSING. If this option is set to NO, conditional code will be ignored, and all code within the condition will be documented. If it is set to YES, the conditional code will be evaluated, and only blocks for which the condition matches will be documented. In this case, you'll need to make sure that all of the values being evaluated are defined correctly, this can be accomplished by allowing doxygen to evaluate include files (see SEARCH_INCLUDES, INCLUDE_PATH and INCLUDE_FILE_PATTERNS options), or by predefining the macros to have a particular value (see PREDEFINED).