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.
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 just discovered some mentions of how nautilus used to read files named .hidden and hide files matching the patterns listed in them, and at some point that feature was moved to GIO g_file_info_get_is_hidden. However, I haven't been able to get it to work. If I put the exact name of a file into .hidden, it does get hidden, but I'd really like to be able to use a pattern. I can't find any solid or recent documentation about how this feature is supposed to work.
I'd particularly like to hide files matching hg-checkexec-*. Mercurial running under Emacs periodically creates bunches of these temporary files and they gum up my nautilus view.
Is this feature documented anywhere? How is it supposed to work?
Looking at the code, .hidden files as implemented in GIO support one filename per line, with no support for patterns. A .hidden file cannot list files in subdirectories — only those in the same directory.
I don’t know of any documentation about the feature. Please file a bug about adding it.
As a complement to Philip Withnall's answer, I've dived further into the source code, specifically the functions read_hidden_file() and file_is_hidden():
read_hidden_file() basically parses the .hidden in a directory and stores each line in as a key in a GLib HashTable object.
The object is created using g_hash_table_new_full() with parameters g_str_hash, g_str_equal, g_free, NULL. This mean keys are plain strings with comparison being a plain (case-sensitive) string equality, so no globs, regex or any patterns support.
It is populated using g_hash_table_add(), so not used as a key/value pair table but rather as a plain set, with keys being the elements themselves.
file_is_hidden() is called for each content (file or sub-directory) in a given directory. It uses g_hash_table_contains() to check if the file's basename is a key in above object, so no pattern search whatsoever.
So, as Phillip concluded, it seems there is indeed no support for any kind of globs, regexes or pattern seach in .hidden files. I would also die for a .gitignore-like syntax.
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.
I'm trying to use \cite in Doxygen to produce a bibliography page and also a reference within my text. I have bibtex in my search path and a proper .bib file. I have added the .bib file to CITE_BIB_FILES and am using a proper BibTex label found in the .bib file. Doxygen is creating a bibliography page, but it is empty. It is also creating a citation link in the documentation text, but the link is also empty. Any idea how I can get the citation info displayed?
I was facing the same problem. There is an perl dependency to generate citation. So you must have both perl and bibtex in the system path.
Ignore the example above, that only applies to Latex, for doxygen use (Note: no braces):
\cite Hale
The .bib file has to be located in doxygen working directory.
Bibliographic References HTML page will be then produced by doxygen with:
[1]J. K. Hale. Theory of functional–differential equations. Springer–Verlag, Berlin–Heidelberg–New York, 1977.
for the following bib entry:
#BOOK{Hale,
author = "J. K. Hale",
title = "Theory of functional--differential equations",
publisher = "Springer--Verlag, Berlin--Heidelberg--New York",
year = 1977
}
In order for \cite to work properly you need:
be sure to put your file.bib in the working directory where you call doxygen Doxyfile
bibtex executable must be in the search path
perl executable must be in the search path
the RefName used in \cite RefName must have a corresponding entry in file.bib
Maybe a little late, but I had the same problem. Doxygen generated a bibliography for LaTeX output, but not for HTML output and none of the proposed answers worked for me.
As suggested by #Raffi, this seems to be a bug in Doxygen < 1.8.3. I used Doxygen 1.8.1.1 and it did not work. Then I installed Doxygen 1.8.3.1 without changing anything else and it worked fine.
When you set CITE_BIB_FILES in DoxyFile did you include the .bib extension on the filename?
Doxygen claims it will automatically add the .bib extension, but if you omit it doxygen seems to gets confused and doesn't generate the citelist.doc file properly.
Include .bib in the filename and it should work fine, at least that is the case for me.
In order to create a bibliography you need to instal Perl, and add it to the search path, along with bibtex. In the documentation
for CITE_BIB_FILES it says:
"The CITE_BIB_FILES ... To use this feature you need bibtex and perl available in the search path ... "
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.