CODEWITHSUNDEEP
doxygen
BobMorane
BobMorane

Reputation: 4306

Make correct doxygen documentation a build requirement

I am using Doxygen to document a C++ project which is becoming bigger and bigger and I have been wondering how I could make Doxygen a build requirement for the project. In other words, I would like my build process to fail and stop if any class/method/etc. has not been successfully documented for Doxygen. I use make for building.

For example, I would like this to fail (i.e. not build):

/**
 * @bbrief Oops, tag does not exist, warning is issued and hence build fails.
 */
void f()
{
    // Do something...
}


/**
 * @brief Main function for program X
 *
 * @return End of execution status.
 *
 * ...
 *
 */
int main()
{
    f();

    return 0;
}

but this to build:

/**
 * @brief Okay, this is fine.
 *
 */
void f()
{
    // Do something...
}


/**
 * @brief Main function for program X
 *
 * @return End of execution status.
 *
 * ...
 *
 */
int main()
{
    f();

    return 0;
}

I have tried searching the Internet for this kind of feature but so far have found nothing.

Upvotes: 3

Views: 2388

Answers (1)

albert
albert

Reputation: 9077

In most cases the documentation is generated but due to the warnings it is incomplete. I see a few possibilities:

  • For this purpose the configuration setting WARN_AS_ERROR is present (see: http://www.doxygen.nl/manual/config.html#cfg_warn_as_error). Possible disadvantage is that process stopes directly when a warning is encountered.
  • catch the warnings in a file and count them / see if the file is empty and based on this decide whether the build was successful or not.

Edit

As noted by @inkychris the WARN_AS_ERROR has, as of doxygen version 1.9.0, the possibility FAIL_ON_WARNINGS. From the documentation:

WARN_AS_ERROR

If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when a warning is encountered. If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS then doxygen will continue running as if WARN_AS_ERROR tag is set to NO, but at the end of the doxygen process doxygen will return with a non-zero status.

Possible values are: NO, YES and FAIL_ON_WARNINGS.

Upvotes: 6

Related Questions