For documentation, we usually have to create an additional document describing what we did when any lint messages were disabled in code (e.g. /* lint --e228).
It would make it much easier to use it with doxygen (as we create this anyhow).
Though, I wasn't able to find any solution on how to make doxygen using these lint comments.
Did anyone try this?
Is there any solution how to use the stric '/*lint' but anyhow add it to doxygen?
Thanks!
This can be accomplished by defining a macro to expand into the lint expression comment, but making the macro expand into a different comment when expanded by doxygen.
The trick is to use the -save instruction to PC-lintTM or FlexeLintTM:
#ifndef LINT_CONTROL
#define LINT_CONTROL(X) /*lint -save X */ //lint X
#endif
int main () {
int a; LINT_CONTROL(-e530)
return a != a;
}
Then, in your doxygen configuration file, you can enable expansion of certain preprocessor macros. In particular, we can change LINT_CONTROL to expand into a doxygen-ated comment instead.
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
PREDEFINED = "LINT_CONTROL(X)=//! lint control: X"
Alternatively, if you have FlexeLintTM, then you can modify the shrouded source so that a doxygen comment can be used to trigger the lint control. The technique is described on the Gimpel Software Discussion Forum. (This link seems dead, and the new discussion forum seems to no longer contain the referenced discussion any longer.)
PC-lint and FlexeLint are trademarks of Gimpel Software.
Related
I was struggling trying to make doxygen work with prolog.
At first I was only trying to include an "external and unknown" file, but as doxygen users know, it won't print a thing if it can't find useful (documented) functions.
Searching stackoverflow for both tags gives no single answer, and so I decided to ask, even if I already solved the puzzle, so people will have a hit in case of search.
I will let this question here, as people can suggest simple workarounds, and we may learn a bit more about the subject, but I'll use it to register my own answer after some (hard) efforts. Thanks.
To explain where I did start:
My first (almost) successful approach worked fine in a program that used both C and PROLOG.
It almost worked because latter on I saw this approach would not work in a PROLOG only project.
Anyway, what I did was simply add this
INPUT = README.md groups.dox c-and-pl.c c-and-pl.pl
FILE_PATTERNS = *.pl
EXTENSION_MAPPING += pl=c
EXTRACT_ALL = YES
EXTRACT_STATIC = YES
SOURCE_BROWSER = YES
And PROLOG code would look like:
/**
* #file cpl.pl
* #ingroup GroupUnique
* #brief CPL - C calls Prolog (Prolog module)
* #cond SKIPPROLOG
*/
/* brief explanation in a normal (non-doxygen) comment */
clause(A) :-
rule(X),
test(A, X).
and(so, on).
/** #endcond */
This would work because C would create the site anyway, and PROLOG page would be just a brief, no clauses, but a link to see the complete code, with normal comments explaining the clauses.
Why this doesn't work for a pure PROLOG project? And how to do that?
My second attempt to solve it involved the creation of a new file, a copy of the original PROLOG source, but with comments in doxygen format, and converting PROLOG clauses in something C-like.
Call the source source.pl and the second copy source.dox. You would write the PROLOG program as you usually do, using doxygen before the first occurrence of each clause, atom, module, etc.
Then cp source.pl source.dox and edit source.dox converting all clauses in something like:
/**
* \file source.pl
* \ingroup GroupUnique
*/
/**
* \ingroup GroupUnique
* \brief Defining factorial module
*/
module(fatorial, [fatpl/2]);
This takes time and are prone to errors, but it was a workaround. Problem is that doxygen now lists source.pl twice. But the functions can be documented. Use this configuration:
INPUT = README.md groups.dox source.pl source.dox
You need to keep source.pl because it is there the real source to be seen. And source.dox would be more like a C header file.
Not good. The work to transform manually a source.pl into a source.dox led me to write my own compiler (well, technically a filter, that uses only lexical tokens).
The program is available open source at github:
https://github.com/drbeco/doxygenprolog
and is cited here in the official pages among other filters: doxygen helpers
And a little note here, in the official SWI-Prolog site:
SWI-Prolog news
To make doxygen work with an unknown language you need:
Install this filter in someplace PATH can find.
Edit your doxygen .cfg to have:
OPTIMIZE_OUTPUT_FOR_C = NO
INPUT = README.md groups.dox source.pl
EXTRACT_ALL = YES
EXTRACT_STATIC = YES
FILE_PATTERNS = *.pl *.prolog *.swipl
FILTER_PATTERNS = *.pl="dox4pl"
Now you can run your doxygen as you normally do with other languages.
I'm using eclipse to work on some c code and it is not indexing code inside conditional compilation blocks like this:
#ifdef USE_FEATURE_A
int feature_a(...) {
some = code(here);
}
#endif
How can I get eclipse to index the feature_a function?
You could tell eclipse that USE_FEATURE_A is defined. Open your project properties and go to the "C/C++ General->Paths and Symbols" page, under the "Symbols" tab click the "Add" button and put USE_FEATURE_A in the name feild and click OK.
Note: this will cause it not to index any #else sides to your preprocessor stuff... so unless they are all like the one in question you can't AFAIK, but if they are they you're good. (Eclipse contains a C preprocessor that it uses to analyize your code all the stuff above does is essentially the same as adding -DUSE_FEATURE_A to your command line so Eclipse's preprocessor will behave differently from the one in your compiler)
This is an easier and in my opinion more elegant solution to the one selected as the solution:
If someone has the same problem (as I had), this can (now?) easily be solved by going to Window->Preference->C/C++/Indexer and enable "Index all header variants".
Then click Project->C/C++ Indexer->rebuild and clean and build your project. This should resolve all error originating from preprocessor commands.
For what it's worth, getting eclipse to parse conditionally compiled code is much harder to do than would appear at first glance. I found a paper on by IBM from 2007 where they said they will prioritize for the "next release".
Handling Conditional Compilation in CDT's Core
I had this same problem, but the code conditionally eliminated by preprocessing was perfectly valid c code and I wanted it formatted... This was my solution:
1) Global find/replace of #if to #JUNKif
2) Ctrl-Shift-F to reformat the source
3) Another global find/replace of #JUNKif to #if
One way to index code under flag in Eclipse(Kepler) c/c++Editor.
You can enable the compilation flags in Eclipse editor so that code under them can be indexed.
Properties > Preprocessor Include Paths > CDT User settings Entries
Click on ADD and add the Preprocessor Macro and you can specify its value.
Best way I guess is to use the Indexer option : Project Properties>C/C++ General>Indexer.
You can choose Enable project specific settings
I prefer choosing "Use active build configuration" so that all files which are actually built in the project are indexed.
Anyhow you can also choose to index all files in the project even if they are not included in the build ...
I'm just getting started with Doxygen, and have done considerable searching on this, so forgive me if there's an obvious answer.
I'm working on an embedded project where functions can be tagged as debug or nodebug before the return type. In most of our libraries, we use a conditional macro to set libname_debug to either debug or nodebug at the top of the file, and then each function is prefaced with libname_debug.
For documentation purposes, I'd like to have Doxygen leave libname_debug out of the function documentation. It clutters up the function list and makes it harder to see the return types of each function.
Is it possible to tag the file in some way so Doxygen will leave that symbol out? At the moment, I'm wrapping each instance in #cond/#endcond:
/** #cond */ libname_debug /** #endcond */
But that's a pain and adds extra markup to the source.
There is also a doxygen page explaining how to handle such situations. You would enable MACRO_EXPANSION (which defaults to NO), tell doxygen to only expand some macros (EXPAND_ONLY_PREDEF) and add your symbol as macro with an empty expansion:
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
PREDEFINED = libname_debug=
You can define macros in the doxygen configuration file. Something like this
PREDEFINED += libname_debug
I have #define values in headers that I certainly want Doxygen to document but I have others in C files that I treat as static constants and I don't want Doxygen to document them. Something as simple and stupid as
#define NUMBER_OF(a) (sizeof((a))/sizeof((a)[0]))
#define MSTR(e) #e
How can I keep Doxygen from putting those #defines in the documentation it creates? I've tried marking it with #internal but that didn't seem to help.
A somewhat-related question on Doxygen and #define, how can I get:
#define SOME_CONSTANT 1234 /**< An explanation */
to put "SOME_CONSTANT" and "An explanation" but not "1234" in the output?
There is no need to use the \cond and \endcond commands. You can hide the initializer by simply using the \hideinitializer command:
#define SOME_CONSTANT 1234 /**< An explanation #hideinitializer */
Regarding the first question, you may set HIDE_UNDOC_MEMBERS = YES and only the macros having a Doxygen documentation block will be shown in the output.
You can set MAX_INITIALIZER_LINES = 0 in your doxyfile to hide the values of your defines.
You can exclude any part of code from Doxygen parsing with \cond ... \endcond tags.
edit: Some related questions:
How can Doxygen exclude a C++ class?
Exclude some classes from doxygen documentation
You only want to document what is declared in the .h files. I'm assuming you declare all static functions and variables as static in your .c files. All the remaining are declared in .h corresponding files also. These are your "public" members.
What I like to do in this case, and I believe doxygen was more designed to be used this way is:
in your Doxyfile, set EXTRACT_ALL = NO and add the directory where your .h files are to INPUT
add /** \file */ to all your .h files (but not your .c files).
This will index only what is contained in your .h files. You can still add the directory containing your .c files to INPUT at your Doxyfile, and they will be scanned for additional documentation for your "public" members...
It will no doubt still seem noisy and unnatural, but to address your other question, try:
/** An explanation */
#define SOME_CONSTANT /** #cond */ 1234 /** #endcond */
I solved this problem by moving my documentation from the .c file to the .h file. Then run doxygen only on the .h file.
Then the items that I want to document (the 'public' items) are intrinsically what doxygen picks up.
Because I have been previously careful to put 'public' items in the .h file and 'private' items in the .c file this works very well.
This technique came to mind when I noticed that doxygen was pulling in the includes. It struck me that if I were to also move the subset of includes that the calling module would need to use my module, then that list would be documented as well.
This technique has an additional benefit: I can put the documentation in one terminal window and the source in a different terminal window while updating the documentation.
Sometimes you may have a define which you want to document, but want doxygen to treat it differently (or even ignore it completely to avoid parsing errors).
For this you can define the #define in doxygen differently than in your sourcecode.
Example:
Some compilers allow variable linkage to specific segments, i.e.:
const int myvar # "segment_of_myvar_in_memory"=123;
=> doxygen would parse the "segment_of_myvar_in_memory" part as variable name which is not desired.
We could use a define for it:
#define __link_to_segment(name) # name
const int myvar __link_to_segment("segment_of_myvar_in_memory")=123;
If Preprocessing is active, Doxygen interprets our variable now as a function because of the function-like define using brackets..
But if we redefine our define within the Doxyfile, behaviour changes:
PREDEFINED = __link_to_segment(a)=
now the variable is parsed correctly as variable - also all types or keywords in front are correctly shown as keywords.
A nice side effekt:
In case you use 2 different IDEs with your code (one IDE for compiling&debugging, one for editing), you will also discover that some IDEs (i.e. Eclipse) have problems parsing variables with #"segment name". Using the approach above, you can redefine the __link_to_segment(name) there too:
#define __link_to_segment(name)
i.e. Eclipse will then show and parse the variable correctly, whereas the "compiling&debugging" IDE can still link the variable to its segment name.
I am working in existing C code which has a couple of lines with statements similar to this one:
struct collect_conn *tc = (struct collect_conn *)
((char *)c - offsetof(struct collect_conn, runicast_conn));
The struct collect_conn goes along the following lines:
struct collect_conn {
struct runicast_conn runicast_conn;
struct announcement announcement;
const struct collect_callbacks *cb;
struct ctimer t;
uint16_t rtmetric;
uint8_t forwarding;
uint8_t seqno;
};
I am using Eclipse CDT, and it marks the line with an orange squiggly line as 'syntax error'. I think it is marked as such by the CDT indexer.
However, compilation (manually in a terminal) is no problem.
This is a bit inconvenient however, since the elements on the line don't get indexed (so the call hierarchy tree isn't always correct, or the highlighting of elements, etc.)
Why does Ecipse not like the line as it is?
Eclipse CDT contains its own preprocessor/parser for analyzing your code and building an index. However, when you invoke a build CDT calls out to your system compiler, like gcc for example. There may be minor differences between the syntax accepted by the CDT parser and the syntax accepted by your compiler. When this happens the CDT parser can get confused.
On my system the offsetof macro expands into an expression that uses the __offsetof__ keyword. This keyword isn't recognized by CDT so that's why there's a syntax error. To deal with this problem the CDT parser has a macro built in to deal with __offsetof__ which looks like this:
#define __offsetof__(x) (x)
This doesn't appear to be correct, at least on my system the result is the removal of the __offsetof__ keyword from the source which still leads to a syntax error.
I was able to get rid of the syntax error by going to the Paths and Symbols property page and adding a macro for __offsetof__ which maps to 'foo'. This tricks the parser into thinking its just a call to a function it hasn't seen before, but not a syntax error.
Alternatively you can turn off syntax error reporting in the editor by going to Window > Preferences > General > Editors > Text Editors > Annotations and unchecking all the checkboxes for C/C++ Indexer Markers.
I've fixed problem in eclipse CDT with Preferences->C/C++->Language Mappings : Add
Content Type : C-header
Language : C++
Sometimes, although the code compiles with no error, eclipse CDT's real-time code analyzer shows some errors in C/C++ files (eg. 'Function xxx could not be resolved). This is because eclipse CDT uses its own preprocessor/parser for analyzing the code and building the indexes instead of the MinGW's one (or any other GNU compiler). In order to fix this globally for all eclipse projects in the workspace, follow these steps:
(In order to fix this only for a specific project, follow steps 1, 2 and 4 in menu 'Project->Preferences')
1-In menu 'Window->Preferences->C/C++->Language Mappings', add the correct mappings as shown in below: (eg. for content types: C++ Source/Header File, use GNU C++ language and so on)
2-In menu 'Window->Preferences->C/C++->Indexer', set full indexing by checking all checkboxes (but not 'Skip' ones) as shown in below:
3-In each project's specific properties, menu 'Project->Properties->C/C++ general->Indexer', Uncheck 'Enable project specific settings' as shown in below:
4-Rebuild the indexing, menu 'Project->C/C++ Index->Rebuild'.
It seems the CDT parser doesn't like the portion offsetof(struct ...).
If you declare collect_conn using a typedef the error goes away. At least for me, the following code works:
typedef struct {
struct runicast_conn runicast_conn;
struct announcement announcement;
const struct collect_callbacks *cb;
struct ctimer t;
uint16_t rtmetric;
uint8_t forwarding;
uint8_t seqno;
} collect_conn;
...
struct collect_conn *tc = (struct collect_conn *)
((char *)c - offsetof(collect_conn, runicast_conn));
If you can't change the original declaration do something like this:
typedef struct collect_conn collect_conn_t;
It might be confused, check if you have a definition of offsetof in-scope, for instance. Otherwise you might try simplifying the expression, breaking it up using e.g. a #define with the offset of, or something.
I'm thinking the compiler might provide a built-in version of offsetof, while Eclipses's compiler/code-parser might not. If so, you would need to make sure you have the definition, for Eclipse to be able to properly parse your code.
try switching the indexer to "Full c/C++ indexer (complete parse)" in Preferences->c/C++ -> indexer
Iv got the same problem. There is 2 definition of offsetof (one for C and one for C++). IMO the problem come from that
For example if i type
#ifndef __cplusplus
#endif
Eclipse will grey it. It mean __cplusplus is defined, but my project is a C
Unfortunatly i dont find a fix.
I fixed similar problem after checking the tab Error Parsers in Makefile Project in New CDT Project Wizard, removing CDT Visual C Error Parser (I am using gcc)
I ended up solving the problem like this. First I opened the project properties, then the C/C++ general->Paths and Symbols category. Under the Symbols tab I added this entry:
Symbol: offsetof(TYPE,MEMBER)
Value: ((ssize_t) &((TYPE *)0)->MEMBER)
These symbols are used by the indexer but not passed to the compiler (at least in Makefile projects, I haven't tried it in the other kind of C project), so it doesn't override GCC's built-in offsetof
I've seen Eclipse do this some times, and I use it for Java. Usually closing and opening the file again fixes it for me (resets whatever is wrong). It usually seems to be an error that WAS there but has been fixed and the "error cache" isn't updated correctly.