I'm generating developer documentation using Doxygen. It's parsing all of the files correctly, but the output is generating duplicate entries in the member function list and class diagram.
Any ideas?
I had this exact problem, and found that I had accidentally specified a build folder in the INPUT line due to RECURSIVE being on, e.g.,
Example file structure:
./
MyLibrarySources/
Libs/
build/
Doxyfile:
INPUT = ./ MyLibrarySources/ ...
RECURSIVE = YES
This caused Doxygen to parse the headers from two different locations: once from MyLibrarySources/, and once from build/, producing duplicate members and other odd results.
The easy solution is to add your build directory to the EXCLUDE line, e.g.:
EXCLUDE = "build"
This makes Doxygen not parse the same header files in two different locations. And yes, in-source build directories are usually a bad idea, place them elsewhere. In my case, command-line builds not issued from my IDE went there by default.
Edit note: I had incorrectly believed that the source files were being parsed twice because of the double-specification in the INPUT line. This is not the case. Doxygen is smart about this and will not parse the same physical file twice 👍.
Related
In the documentation of pythonforandroid, at https://python-for-android.readthedocs.io/en/latest/buildoptions/, there is a build option described called blacklist.
--blacklist: The path to a file containing blacklisted patterns that will be excluded from the final APK. Defaults to ./blacklist.txt
However, not a word can be found anywhere about how to use this file and what exactly the patterns are supposed to represent. For instance, is this used to exclude libraries, files, or directories? Do the patterns match file names or contents? What is the syntax of the patterns, or an example of a valid blacklist.txt file?
This file should contain a list of glob patterns, i.e. as implemented by fnmatch, one per line. These patterns are compared against the full filepath of each file in your source dir, probably using a global filepath but I'm not certain about that (it might be relative to the source dir).
For instance, the file could contain the following lines:
*.txt
*/test.jpg
This would prevent all files ending with .txt from being included in the apk, and all files named test.jpg in any subfolder.
If using buildozer, the android.blacklist_src buildozer.spec option can be used to point to your choice of blacklist file.
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.
I'm new with Doxygen, and i have been commenting my functions with the Qt style approach:
/*! .. */
Doxygen however only picks up my header files and does not generate documentation of any text that is within these comments.
The html file rendered, shows a completely empty main page, "Classes' only list the structs
that are found in the header files and "Files" lists only the same header files in the project.
What may cause this behavior, or is this to be expected?
Am i missing something? The only thing i changed in the configuration file was the INPUT directory to be "src".
No errors during compilation, i see that it is preprocessing and parsing my .c files. And at some point it says this, but only for the header files
Generating code for file src/foo.h...
Generating code for file src/bar.h...
etc.
Finally i get some warnings about structs not being documented, but nothing about the functions I want to have actually documented.
I am trying to run doxygen on some source files for a project that I downloaded source files for. The files are located in the following directories:
doc/ - Documentation files, such as .dox files.
src/ - Source files
My settings in my doxygen.config file are:
INPUT = ../ .
FILE_PATTERNS = *.h *.dox *.dxx
When I run doxygen (doxygen doxygen.config), it generates all of the documentation from the .h files correctly, but it does not generate the mainpage correctly. I have a file titled intro.dox in the doc folder, with a command \mainpage Documentation Index, and a bunch of text, but doxygen is not using this to generate the main page.
What am I doing wrong?
There are (at least) two possible reasons for this:
You are not including the /doc directory in you INPUT list. Try modifying this to
INPUT = ../ . ../doc
Did you mean to write ../doc instead of ../? I am guessing that your doxygen.config file is in your src directory. If this is not the case can you make this clear in the question.
Doxygen requires that your documentation files (your .dox files) are plain text with your text wrapped with Doxygen C++ comments (i.e. /** ... */).
Without knowing where doxygen.config is located, and since you are using relative paths in INPUT, it is difficult to determine what might cause this, however since the files you are looking for are in parallel directories, it is possible that doxygen is not search recursively for your files. You may want to confirm that RECURSIVE is set to YES in doxygen.config.