How can one run doxygen in "verification" mode? (parse all documentation, and emit warnings if so configured, but generate no output files).
I tried with the following doxygen configuration file:
DOXYFILE_ENCODING = UTF-8
QUIET = YES
INHERIT_DOCS = YES
EXTRACT_STATIC = YES
EXTRACT_PRIVATE = NO
WARN_NO_PARAMDOC = YES
WARN_IF_UNDOCUMENTED = YES
WARN_IF_DOC_ERROR = YES
WARN_FORMAT = $file($line): $text
GENERATE_HTML = NO
GENERATE_LATEX = NO
INPUT += MySource.cs
Source file:
/// <summary>
/// My namespace documentation
/// </summary>
namespace MyNamespace
{
/// <summary>
/// My class documentation
/// </summary>
public class MyClass
{
/// <summary>
/// My function documentation
/// </summary>
/// <param name="param">The parameter</param>
/// <returns>My return value</returns>
public bool MyFunction(string param)
{
return true;
}
}
}
This generates the following warning:
warning: No output formats selected! Set at least one of the main GENERATE_* options to YES.
which is a bit of a bummer since I want to set WARN_AS_ERROR = YES. But additionally I get additional errors like:
MyClass.cs(17):warning: parameters of member MyNamespace.MyClass.My
Function are not (all) documented
MyClass.cs(17):warning: return type of member MyNamespace.MyClass.M
yFunction is not documented
If I set GENERATE_HTML = YES however I have no warnings, so the documentation itself is fine. Am I doing something wrong or is this a bug?
Doxygen is not intended for just checking whether or not the documentation is complete. The purpose of doxygen is to generate documentation. Some error first appear when the complete documentation is generated / can be properly checked when the documentation is generated.
Workaround: Set the QUIET = YES and WARN_LOGFILE configuration option to a file, then parse the content of this file. The warning
warning: No output formats selected! Set at least one of the main GENERATE_* options to YES.
is not being printed to that file.
Related
I want to generate documentation only for code that has Doxygen comments. I have created a Doxyfile via Doxygen version 1.8.9.1 and configured it to output only XML and to hide all undocumented code:
GENERATE_HTML = NO
GENERATE_LATEX = NO
GENERATE_XML = YES
HIDE_UNDOC_MEMBERS = YES
HIDE_UNDOC_CLASSES = YES
After that I created a simple C header test.h with one documented and one non-documented function declaration:
void foo(int a);
/**
* "bar" function description
* #param b sample param
*/
void bar(int b);
By executing doxygen I expected only documentation for bar to be included in the resulting XML. Unfortunately, documentation for both functions is generated. Is it possible to generate documentation only for code that has Doxygen comments? Or will Doxygen always include everything in the XML output regardless of settings?
Before reading any further make sure EXTRACT_ALL is set to NO.
I'm not a fan of the following solution but it does work. Use doxygen's preprocessor
#ifdef PROJECT_NO_DOC
void foo(int a);
#endif /* PROJECT_NO_DOC */
/**
* * "bar" function description
* * #param b sample param
* */
void bar(int b);
Note, in their docs you have to set a PREDEFINED macro but at least in my version of doxygen this was not required. Their docs specify to do it this way set a predefined macro in the config to do it for you
#ifndef DOXYGEN_SHOULD_SKIP_THIS
/* code that must be skipped by Doxygen */
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
around the blocks that should be hidden and put:
PREDEFINED = DOXYGEN_SHOULD_SKIP_THIS
in the config file then all blocks should be skipped by doxygen as long as
ENABLE_PREPROCESSING = YES
There are other methods but they come with additional constraints ie to make sure no static method appear in your public docs you can set EXTRACT_STATIC to NO.
You can use \cond to hide parts of the source code from Doxygen. This avoids the need to use the preprocessor as in Harry's answer.
For example, here foo will not be seen by Doxygen, and hence not documented:
/** \cond */
void foo(int a);
/** \endcond */
/**
* "bar" function description
* #param b sample param
*/
void bar(int b);
Furthermore, it is possible to add section labels to \cond, and control which sections are included by listing them in the ENABLED_SECTIONS configuration option.
For example:
/// \cond CLASS_A
/// This function foos `a`.
void foo(int a);
/// \endcond
/// \cond CLASS_B
/// This function bars `b`.
void bar(int b);
/// \endcond
By setting ENABLED_SECTIONS = CLASS_A CLASS_B, both functions will show up in the documentation. Leaving one of the labels out will hide the corresponding function.
I am using doxygen 1.8.9.1 and bibtex to generate the reference list. It looks doxygen (or bibtex) don't support longer key.
For example, my bib file looks like
#incollection{mcmaster_phenology_,
title = {The {DSSAT} cropping system model},
volume = {18},
journaltitle = {European Journal of Agronomy},
author = {A, F.},
}
#article{mcmaster_phenology_1,
title = {The {DSSAT} cropping system model},
volume = {18},
journaltitle = {European Journal of Agronomy},
author = {A, F.},
}
My text.cs file looks
namespace Test
{
/// <summary>
/// A test class
/// </summary>
/// <remarks>
/// This is test citation, see \cite mcmaster_phenology_ and
/// \cite mcmaster_phenology_1.
/// </remarks>
public class TestClass
{
}
}
The warning message is:
warning: \cite command to 'mcmaster_phenology_1' does not have an associated number
The final html is
This is test citation, see [1] and [mcmaster_phenology_1].
Seems the maximum length of key is 19 characters. It looks a bug for me. How should I fix it? Thank for any suggestions.
Setting SOURCE_BROWSER = TRUE show source code for all files.
Is it possible to show source of specific file?
Or enable \ref or equivalent using SOURCE_BROWSER = FALSE
Or remove source code for specifics files if SOURCE_BROWSER = TRUE
Or equivalent
It is possible using \include and \verbinclude.
/**
* \verbinclude Example.cs
* \include Example.cs
* */
public class Example
{
}
I am using doxygen to create a HTML documentation for a C++ library.
Right now I have the problem that code listings created with \code ... \endcode produce listings where each line starts with an asterisk.
Example:
Have a look at the following code sample:
\code
int a = 5;
int b = func(a);
\endcode
Output:
Have a look at the following code sample:
* int a = 5;
* int b = func(a);
I cannot explain this behaviour -- especially because I use /// instead of /** to mark lines as doxygen documentation. The issue happens for both formattings though.
Does anyone know how to resolve this?
(I am using doxygen 1.8.5)
This is indeed an unfortunate regression in 1.8.5.
I've just pushed a fix to GitHub. Please let me know if it fixes the problem.
It seems this is a bug. Bugzilla entry.
Also this bug could be related.
I managed to get a workaround by changing the following snippet
/// Have a look at the following code sample:
/// \code
/// int a = 5;
/// int b = func(a);
/// \endcode
to the following (note that there are only two slashes):
/// Have a look at the following code sample:
// \code
// int a = 5;
// int b = func(a);
/// \endcode
I am not happy with this because it requires to re-layout all comments and the formatting feels very much unnatural.
I have this PACKED macro, that receives a struct definition and returns it with a compiler annotation to make it packed.
For example:
/**
* ...
*/
PACKED(struct A {
/**
* ...
*/
int x;
});
I have tried several Doxygen options to include that documentation, but I've had no success so far. Closest I've come up with is this:
ENABLE_PREPROCESSING = YES
PREDEFINED = PACKED(type)=type
MACRO_EXPANSION = YES
But that messes up the struct and members' documentation (confirmed via doxygen -d Preprocessor).
Ideas?
Turns out it's a bug in Doxygen.
One possible workaround is to use #class, and so on.