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.
Related
In my configuration file in the INPUT tag I added one directory. Inside that iostream is there without any extension. After running the configuration file I'm not getting information related to iostream. I want to know how to add the files without extension in doxygen configuration file.
I created a small test example (contents is not that relevant for this test), file stdio:
/// the fie
void fie(void);
From the documentation (https://www.doxygen.nl/manual/config.html#cfg_extension_mapping):
EXTENSION_MAPPING
Doxygen selects the parser to use depending on the extension of the files it parses.
With this tag you can assign which parser to use for a given extension. Doxygen has a built-in mapping, but you can override or extend it using this tag. The format is ext=language, where ext is a file extension, and language is one of the parsers supported by doxygen: IDL, Java, JavaScript, Csharp (C#), C, C++, D, PHP, md (Markdown), Objective-C, Python, Slice, VHDL, Fortran (fixed format Fortran: FortranFixed, free formatted Fortran: FortranFree, unknown formatted Fortran: Fortran. In the later case the parser tries to guess whether the code is fixed or free formatted code, this is the default for Fortran type files).
For instance to make doxygen treat .inc files as Fortran files (default is PHP), and .f files as C (default is Fortran), use: inc=Fortran f=C.
Note: For files without extension you can use no_extension as a placeholder.
Note that for custom extensions you also need to set FILE_PATTERNS otherwise the files are not read by doxygen.
Here we see that the possibility for no_extension and with the following setting we get the requested information:
EXTRACT_ALL=YES
INPUT = stdio
EXTENSION_MAPPING = no_extension=C++
and I do see the stdio information.
Edit
In case doesn't want to add all files one by one one hast to add * to FILE_PATTERNS.
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.
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 need to refer to Doxygen documentation pages. The file names however are not stable as they change after every generation. My idea is to create a symlink to each HTML file created by Doxygen , having a stable and human friendly name. Have anyone tried this?
Actually, it might be very easy just to parse the annotated.html file Doxygen produces. Any documented class shows up there as a line like:
`<tr><td class="indexkey"><a class="el" href="dd/de6/a00548.html">
ImportantClass</a></td>`
The hard problem for me is that I would like to have my file names (i.e. the symlinks) be visible on my server like:
http://www.package.com/com.package.my.ImportantClass.html
[Yes, the code is in java]. So the question actually reads: "how to connect a HTML page by Doxygen with the right java class name and its package name.
You seem to have SHORT_NAMES enabled, which will indeed produce volatile names. When you set SHORT_NAMES to NO in the configuration file (the default), you will get longer names, but these are stable over multiple runs (i.e. they are based on the name, and for functions also on (a hash of) the parameters.
So I'm new to using Doxygen and I was able to get it to work smoothly. I was able to document my classes and structs and it generates the HTML files perfectly. The issue I'm running into is it won't parse my main.cpp file. All the classes and structs have their own .h and .cpp files and they process fine. How do I get Doxygen to make the documentation for main.cpp? It doesn't have a .h file as this is where the program starts and ends. I wouldn't even know what to put in the .h file for main. I'm using Doxywizard in Windows.
Edit:
I put this in main and it generates a main page:
/**
#mainpage
This is a test application.
#author Alex
#date 10/21/2010
#version 1.0
*/
But then farther down the file where the function prototypes are I have this and it doesn't get parsed:
/**
#brief Error handler for the PDF writer.
It does nothing. It just has to exist.
*/
void error_handler (HPDF_STATUS error_no,
HPDF_STATUS detail_no,
void *user_data)
{
}
I put this at the top of main.cpp and it worked. Go figure.
/**
#file main.cpp
*/
If INPUT and FILE_PATTERNS are empty, it should search for *.cpp files (and many other patterns) in the current directory. (This from the doxygen manual.)
Since yours are empty, I expect one of two things is going on if you're not getting main.cpp documentation:
main.cpp is not in the current directory. To rule this out, make sure you're running doxygen from the same directory as both your config file and main.cpp.
There is a syntax error in your main.cpp documentation. These can be tricky to spot, as doxygen doesn't generally abort when it encounters an error - instead it just skips ahead. If this is the problem, comb through doxygen's output when you generate your docs line by line.
If neither of these ideas solve your problem, we might need more information. Output of ls -R, output of the doxygen run, etc. Good luck!
I did some research on this... From the doxygen manual :
Important: The documentation of global functions, variables, typedefs,
and enums will only be included in the
output if the file they are in is
documented as well.
There you go !