Is there a way to suppress Doxygen from giving "not documented" warnings on particular files? My project has several automatically generated code headers that cause it to throw hundreds or thousands of errors that make it difficult to sift through.
You could use suppression tags in the generated files:
//! #cond Doxygen_Suppress
code
//! #endcond
You don't need the "Doxygen_Suppress" in there, but I like it for clarity.
There are more options in the doxygen FAQ
EDIT:
Ok, I should have done my due diligence, I have an answer that is more appropriate to your situation. I believe you need to exclude the files entirely. Add this to your doxygen file:
# The EXCLUDE tag can be used to specify files and/or directories that should
# excluded from the INPUT source files. This way you can easily exclude a
# subdirectory from a directory tree whose root is specified with the INPUT tag.
EXCLUDE = abc.cpp \
abc.h
The irony is I have had this problem and solved it, then forgot all about it... Brain must be full again.
I pulled this information from the doxygen Configuration page, but if you are lazy like me, just use the gui tool (doxywizard) and go through and select all the things you want and have it save the doxyfile for you.
There's a config option for that, as stated in documentation
WARN_IF_UNDOCUMENTED
If WARN_IF_UNDOCUMENTED is set to YES, then
doxygen will generate warnings for undocumented members. If
EXTRACT_ALL is set to YES then this flag will automatically be
disabled.
In my automatically generated headers I just add the doxygen documentation into the auto-generation routine.
This means that nothing is left undocumented.
If anyone is using Eclipse, I definitely suggest to open your file (*.doxyfile) with a text editor (note that eclipse open it with "Doxyfile Editor" by default).
So:
right click on your doxyfile and select "open-with"->"text editor"
search for WARN_IF_UNDOCUMENTED (setted 'YES' by default)
change in 'NO'.
Adding tags
//! #cond Doxygen_Suppress
code
//! #endcond
if you have many classes should be boring and hard.
Documentation for other configuration's options are available here.
Related
Doxygen has a \file command, I had a look at different code bases and it seems some projects use it, some don't.
Having to maintain this adds some overhead (needs to be corrected when splitting files up) sometimes developers forget to do it.
Is there a way to infer this, eg: use the first doxygen formatted comment in the file as the \file comment.
Otherwise what is a good rule of thumb for when to use \file or not?
Note, I tried removing this command from all files and the output changed to group information less usefully and the order of some information changed, so it does make a difference.
I am trying to separate out internal and external documentation using the doxygen constructs of cond; but i just cant seem to get get it working. I would essentially like to exclude some files completely and not conditionally. Regardless of where i add the tag (before include, before header guards etc) , the files and source both show up.
What i have tried in vain is to take the test file from doxegen repo for
conditional test and add it to the project.
Steps to reproduce [Linux]
create a new directory.
copy paste the above file (had to rename it to .h as .c was passed over?).
generate dummy config via doxygen -g.
update Doxyfile ENABLED_SECTION = COND_ENABLED.
Run doxygen.
check html/index.html
This however is still visible in the html documentation it generates for the project. I have set the ENABLED_SECTION variable with other values , but cond_enabled function still shows up. Running the testing directory of the project (doxygen) it passes. So i am lost.
Any suggestions?
Tried with latest version 1.8.14.
Thanks!
Regarding the \cond problems (not an answer directly to the real problem you face, I think, but to long for a comment).
The mentioned file is used in the, limited, testing doxygen can do / does and the first lines contain some instructions on what to do. Furthermore there is a default Doxyfile with the tests in use. It is hard to run a separate test outside the doxygen build tree.
Regarding the remark "Running the testing directory of the project (doxygen) it passes." This is correct, here, at the moment, only testing is done against the XML output and the generated output is compared to a once created version of the XML output. No tests are done, at the moment, in respect to HTML or PDF / LaTeX. Recently the test framework has been slightly extended so in the future this should be possible (compare the xhtml and tex output, but some work has still to be done here).
The version of the parser sees the \cond in the first line (normal C comment) as a doxygen command and skips everything till the first \endcond (your friend in these cases is always doxygen -d preprocessor). I think that removing / modifying the first line will result in an already better result. There is however another hiccup for e.g. HTML output. As the function cond_enabled is not documented and EXPAND_ALL is not set to YES the function will not appear in the documentation. So best is also to add a line of documentation with the function cond_enabled.
Regarding the seen HTML problems I modified the the relevant test in doxygen slightly and pushed a proposed patch to github (pull request 714, https://github.com/doxygen/doxygen/pull/714).
Note: the problem of skipping the \cond in normal C comment is quite a bit harder to implement (seen the logical complexity of the doxygen code in pre.l and commentcnv.l.
EDIT: 2018/06/10: The push request has been integrated in the master version on github.
So, we are using doxygen in a big project.
Some of the source code is generated during the build,
like my_generated_code_fragment.h
It is used in the source code, like this
file foo.cc
void foo()
{
#include "my_generated_code_fragment.h"
}
Now, when running doxygen from the repository under source control,
doxygen rightly complain that file my_generated_code_fragment.h is missing,
with an error like:
foo.cc:1234: warning: include file my_generated_code_fragment.h not
found, perhaps you forgot to add its directory to INCLUDE_PATH?
Problem
We don't want to perform a full build first, just to generate the missing
files, in order to generate documentation.
Note that the generated code does not contain doxygen comments anyway.
Solution considered so far
Do Nothing
Do nothing and ignore doxygen errors.
Not really satisfactory.
Generate dummy files
Generate dummy files like my_generated_code_fragment.h prior to running
doxygen.
This creates complications in the build scripts,
where "using doxygen" is now different on different projects,
because the files containing generated code differs.
Use preprocessor flags
Change the code to
void foo()
{
#ifndef IN_DOXYGEN
#include "my_generated_code_fragment.h"
#undef IN_DOXYGEN
}
and set PREDEFINED
This is the best solution considered so far, but it means changing the code.
Question
Is there a better option, like tell doxygen using a setting in Doxyfile
that file my_generated_code_fragment.h is expected to be missing,
and should be ignored ?
Note:
EXCLUDE does not work for this,
as the error is seen when parsing file foo.cc, not when parsing the generated code.
Using doxygen version 1.8.5 at the moment.
Documenting the solution taken then.
Solution 3, to use pre-processor flags when building with doxygen, and changing the (small) parts of the code that uses generated content worked well.
This allows to use doxygen on "raw" source code, pulled from git.
Is any way to not generates warrnings from undocumented function/method that is located in source file ( .c ) . I have all comments in header file and do not want to duplicate it.
I do not want to switch off documenting source code but only comments for method in this file.
Thanks in advance for any suggestions.
I can think of two approaches you could take, both by changing config options in your Doxyfile:
If you set WARN_IF_UNDOCUMENTED to False (it defaults to True), doxygen won't complain about any function or method which is undocumented. (You might not want to do that though, as the warnings can be a helpful way to check you've documented all your methods and functions.)
Set your config to include or exclude files based on their suffix. For example: if the methods and functions which are causing problems all have a .c suffix, you can set EXCLUDE_PATTERNS to *.c to ignore all .c files.
The doxygen configuration documentation is pretty comprehensive, and you may find another approach in there which suits better.
I'm using Eclipse and Doxygen on a Linux platform. My teams code is controlled with Clearcase. My question is can I use an environment variable as part of the path to excluded?
example: every one on the project has a custom view as part of their path. And I don't want to see that in the documentation.
/view/me/a/b/src/.../...
/view/you/a/b/src/.../...
in each developers view their is an environment variable defined with their view name. ex: $CLEARCASE_ROOT = /view/me
So I'm trying to setup a single Doxygen file for whole team to use..
So I want to do something like EXCLUDE ${CLEARCASE_ROOT}/a/b
Then everybody that generates docs will get the same paths.. Can I do this??
Thanks.
Yes, doxygen supports environment variable expansion in its configuration files, see http://www.doxygen.nl/manual/config.html.
The EXCLUDE option controls which files are parsed by doxygen. It sounds like you want the files to be included, but you want them to be displayed with a relative include path, in that case you probably want to use the STRIP_FROM_INC_PATH option. If there are other absolute paths in the documentation you're attempting to make relative, the STRIP_FROM_PATH option may also come into play.
The syntax is a little different than what you proposed, $() vs. ${}, so you'll want to specify something like:
STRIP_FROM_INC_PATH = $(CLEARCASE_ROOT)/a/b
STRIP_FROM_PATH = $(CLEARCASE_ROOT)