I am using doxygen to generate html help for our C++ API.
There are parts which are enabled/disabled in code such as
#ifdef EXPERIMENTAL_FEATURE1
class Experimental1
{
...
}
#endif
#ifdef EXPERIMENTAL_FEATURE2
class Experimental2
{
...
}
#endif
I set my doxygen PREDEFINED as follows:
PREDEFINED = EXPERIMENTAL_FEATURE1 EXPERIMENTAL_FEATURE2
This however doesn't cause doxygen to extract doc. for these classes. Log shows that doxygen reads the files.
Is the syntax for PREDEFINED correct (separated by space and without =)?
How can I debug this?
Have a look into the doxygen manual:
http://www.doxygen.nl/manual/preprocessing.html
The typical syntax is:
PREDEFINED = "name1=value1" \
"name2=value2" \
"name3=value3"
In more detail the manual says:
The argument of the tag is a list of macros of the
form: name or name=definition (no spaces). If the definition and the "=" are omitted, "=1" is assumed.
To prevent a macro definition from being undefined via #undef or recursively expanded use the := operator
instead of the = operator.
If you have no value you can simply write "name" - so your example should work.
Make sure that the following settings are correct within your doxyfile:
HIDE_UNDOC_CLASSES=NO
EXTRACT_ALL=YES
EXTRACT_LOCAL_CLASSES=YES
Otherwise classes aren't put into the documentation.
Also make sure ENABLE_PREPROCESSING is set to YES.
If all this doesn't help please post a minimal example that reproduces the problem.
Related
I want to use doxygen to document a c-like language.
I got some issues to solve keywords which are unknown in the context.
One example, I have to use a callback function called
on timer
{
//normal c- code
}
My question is now, can I adopt doxygen to accept the new keyword?
I would like to add this keyword like a function or variable acc. to
/** This timer is used for something. */
on timer
{
}
or maybe
/** \ontimer This timer is used for something. */
on timer
{
}
The documentation of doxygen describes something with ALIASES or \xrefitem but as I understand I can only generate new sections for known types or am I wrong?
Actually I am surrounding the unknown code with a condition block out to avoid errors in the generated output.
As I understand is "on" a keyword which doxygen cannot interpret. One solution could be to declare the keyword on as a predfined macro in the doxyile by using the the PREDEFINED tag as follows:
PREDEFINED = on=
Yes, the = at the end is not a typo! This tells the preprocessor of doxygen to substitute the keyword on with a empty string. Note that you have to set ENABLE_PREPROCESSING to YES.
If the on keyword only appears before callback functions you could alternatively set the PREDEFINED macro to void:
PREDEFINED = on=void
I want Doxygen to document the code written in C-like language (PARI/GP) but having slightly different syntax. I believe Doxygen can document the entities those do not exist. It seems to be the simplest way to do the job while the programming language is not Doxygen-supported. I want something like this:
/*!
\fn foo(param,{option})
\brief some brief description here
\param[in](param) mandatory parameter description
\param[in](option) optional parameter description
*/
/*! \cond DOXYGEN_SHOULD_SKIP_THIS */
foo(param, {option}) =
{
...
};
addhelp(foo, "help message for `foo` function");
/*! \endcond */
Unfortunately, Doxygen generates the warning "documented symbol 'foo' was not declared or defined" and does not list the foo in an output HTML. Is there any way to force the Doxygen to produce the proper HTML using only the documentation blocks but not the code?
There are various options
You could write an input filter that translates your code into something that looks enough like C for doxygen to parse it (see also FILTER_PATTERNS and EXTENSION_MAPPING).
You could create a dummy C file with the function prototypes and document those instead. You could put the documentation in the C file or in your programming language if you use the approach you mentioned in the question.
If your language supports a C preprocessor, you could use doxygen's C preprocessor to hide parts of the file from doxygen, i.e.
#if DOXYGEN_ONLY
/**
\brief some brief description here
\param[in](param) mandatory parameter description
\param[in](option) optional parameter description
*/
void foo(param,option);
#endif
foo(param, {option}) { ... };
and then define the following in the config file:
PREDEFINED = DOXYGEN_ONLY
I'm working on a project which defines globals like this:
// Define an correctly-sized array of pointers to avoid static initialization.
// Use an array of pointers instead of an array of char in case there is some alignment issue.
#define DEFINE_GLOBAL(type, name, ...) \
void * name[(sizeof(type) + sizeof(void *) - 1) / sizeof(void *)];
Which apparently works fine, but causes Eclipse to show every single usage of one of these globals as an error.
I would prefer that it be this:
#define DEFINE_GLOBAL(type, name, ...) \
type name;
But I can't change this file, so is there a way to tell Eclipse to pretend that that's the macro's definition?
If you #define the preferred definition after the initial (unwanted) definition, Eclipse seems to use the most recent definition when it does the dynamic macro expansion.
Thus, if you re-#define the macro in the file you are editing, this may solve your problem.
Granted that this is a kludge and may cause unforeseen problems, it may work for your implementation.
I was reading through the Journo's source code and I stumbled upon this line of code:
markdown = _.template(source.toString()) variables
What is variables doing here? Is _.template(source.toString()) variables valid stntax at all?
Here's the function wrapping that line of code:
Journo.render = (post, source) ->
catchErrors ->
do loadLayout
source or= fs.readFileSync postPath post
variables = renderVariables post
markdown = _.template(source.toString()) variables
title = detectTitle markdown
content = marked.parser marked.lexer markdown
shared.layout _.extend variables, {title, content}
Yes, it is valid. Parenthesis are optional (sometimes) in CoffeeScript when invoking a function, so it is taking the result of template and invoking it with arguments. It compiles to this JavaScript:
_.template(source.toString())(variables);
From the CoffeeScript documentation:
You don't need to use parentheses to invoke a function if you're passing arguments. The implicit call wraps forward to the end of the line or block expression.
_.template compiles a template specified by source.toString(). A template is a function, which is then called. variables is a parameter for that function (just like postPath post are parameters for fs.readFileSync).
See also the docs for _.template
The question was nicely answered, but to help the OP with future coffee stunts, a great way to anser these koans is to
Go to the coffeescript.org site
Click on "Try coffeescript"
Cut/Paste the puzzle into the coffeescript section
Bingo! You see the generated javascript.
I admit to puzzling over coffeescript at times, and this is abs fab .. and saves headaches.
Example: I want to do this:
METHODNAME(5) {
// do something
}
which results in:
- (void)animationStep5 {
// do something
}
Is there any way to do this? Basically, what I need is a way to generate a real source code string before the program is compiled, so the compiler does see - (void)animationStep5...
Or maybe there's something different than a macro, which can help here to auto-generate method names (not at run-time)?
As was already answered here, the objective-C preprocessor is very close to the C one.
You should have a look at the examples posted there, and have a look at C proprocessor. You will simply have to use the ## syntax of the preprocessor, to concatenate the method name, and the number you want.
You can use the concatenation operator
#define METHODNAME(i) -(void)animationStep##i
you can call it like
METHODNAME(5){}
This expands to
-(void)animationStep5{}
Assuming the objective-c preprocessor behaves the same as the standard C one, you can use something like:
#define PASTE(a, b) a##b
#define METHODNAME(n) PASTE(animationStep,n)
to join the required bits together. This means that
METHODNAME(5)
gets translated to
animationStep5
(you may need to add the "void" from your question to the macro definitino depending on exactly what it is you need to do).