3

Is there a way to suppress the "documented symbol 'x' was not declared or defined" Doxygen warning for certain parts of the code?

I know similar questions have been asked at least here and here but I did not find the answers posted to those questions helpful for my case so I wanted to check if there were any solutions or ideas that would help in this use case.

So first of all, I need to have WARN_AS_ERROR=FAIL_ON_WARNINGS so that Doxygen exit code will be non-zero when there are (valid) warnings so that my pull request checker can detect issues correctly. In this case, however, Doxygen incorrectly claims that some documented symbols are not declared because it's unable to parse their declarations due to the way their declarations come from external library code (see below). So I would need that particular warning to be suppressed for the definitions of those particular functions. The documentation for those functions should still be processed and warnings about any other issues in that processing are very desired. Hence, to my understanding, @cond does not solve this. Is there anything that does?

For reference, this is where the undesired warning originates from although I don't think it should matter for the question: in file c.h:

//! blabla
namespace A
{
  //! blabla
  namespace B
  {
    //! blabla
    class C
    {
#include "lib.h" // This is where the function declarations are but Doxygen does not figure it
    };
  }
}

in file c.cpp:

using namespace A::B;

/*! The declaration of this function was in lib.h. I may document something additional here but Doxygen collects this function without that also, which is desired.
*/
void C::foo()
{
}
Iksa
  • 53
  • 6
  • 1
    That is an unusual way to declare functions of a class. – Eljay Dec 31 '22 at 12:30
  • @Eljay I know. They are actually virtual functions that a client of the library is supposed to override. For simplicity, I did not mark the inheritance in the example. I guess the intent of the library writer has been to save the client from excessive typing. Anyway, while it would likely be beneficial to have better parsing in Doxygen, from the point of view of this question it shouldn't really matter what the warning is or where it's coming from. – Iksa Dec 31 '22 at 12:42
  • 1
    Which version of doxygen? What did you try with `@cond`? Maybe you should implement a default version of the function to be overridden by the user and protect it with `#if DOXYGEN` and in the doxygen settings file set the appropriate `PREDEFINED` etc. – albert Dec 31 '22 at 12:45
  • @albert Doxygen version 1.9.6 and Windows 10 Pro. I didn't try anything with `@cond` because the documentation at https://doxygen.nl/manual/commands.html#cmdcond says "The main purpose of this pair of commands is to (conditionally) exclude part of a file from processing...". I didn't quite get what you meant with the `#if DOXYGEN` thing, can you elaborate please. You didn't mean to suppress processing of those functions, did you? I want them to be processed and other warnings generated when justified, just this unjustified warning to be suppressed. – Iksa Dec 31 '22 at 13:36
  • What I meant with `#if DOXYGEN` is that you create a real function so that doxygen finds the correct function and doesn't emit a warning but you probably don't want to have this function in your (compiled) code base so you need a guard (with name DOXYGEN). In the Doxyfile you set the `PREDEFIND+= DOXYGEN=1` (and `MACRO_EXPANSION=YES` etc.) so doxygen thinks the function is present and in the normal compilation `DOXYGEN` is not set so it will ignore that part. – albert Dec 31 '22 at 13:58
  • I might be mistaken. It does not appear (to me) that Doxygen performs a C preprocessor on the file. Rather it seems that Doxygen collects a set of files to parse for Doxygen comment tags, collates those, and organizes & cross references them. My guess is the use of a `#include` in the middle of a block is something that Doxygen does not parse, so it does not automatically make the correct symbol names for cross referencing. – Eljay Dec 31 '22 at 14:27
  • Thank you guys for your super quick replies. @albert ok got it. But that would pretty much ruin the whole idea of not cluttering the codebase by repetitive code by using an included file and be a nightmare to maintain unless I auto-generate the declarations for doxygen somehow but that would make it overly complex. In real life there's not just a single function but hundreds of functions included by more than one source code file. – Iksa Dec 31 '22 at 15:23
  • @Eljay I've got the same assumption on Doxygen's usage of C preprocessor. But I intended the sample code to be just an example of the problem. If there were a way in Doxygen to suppress an arbitrary type of warning for the processing of a specified piece of code while allowing justified warnings to be issued for the same piece of code, it would also be a solution for every similar future problem, and not require Doxygen to perform C preprocessor. – Iksa Dec 31 '22 at 15:38
  • Doxygen should process the include files. I think the cluttering might be minimal, it would probably be possible to place the doxygen extra code in a separate file. – albert Dec 31 '22 at 16:48
  • Not sure if it matches correctly, but this method worked for me https://stackoverflow.com/questions/40358150/doxygen-demands-that-an-include-guard-be-documented – CoderAtWork Apr 06 '23 at 02:49
  • @CoderAtWork That is a functional workaround. Thank you! – Iksa Apr 07 '23 at 12:14

0 Answers0