Added support for suppressing certain cpp domain warnings.

[rsanchez15]

Subject: This pull request adds two tags for the suppression of warnings raised by the cpp domain.

Feature or Bugfix

• Feature

Purpose

This pull request is intended to continue the expansion of the work implemented in #2346 through the addition of new types for the suppression of warnings. Specifically, this pull request focuses on warnings raised from the cpp domain when declaring C++ functions and variables.
A new type and two subtypes of warning are added.

• cpp.duplicate_declaration
• cpp.parse_function_declaration

Detail

• cpp.duplicate_declaration: Removes the warnings caused by the duplicate declaration of functions. The purpose of removing this warning is to allow functions with the same name to exist within the same project.
• cpp.parse_function_declaration: Removes warnings caused by errors in the parsing of function declarations. This warning occurs in function statements such as the following:
  const MyStruct const_struct(0,0)

[jakobandersen]

Can you elaborate a bit on the rationale behind this? Perhaps there are better ways to solve the original problem.
I'm confused about your code const MyStruct const_struct(0,0), as it really isn't a function declaration, so the warning seems quite appropriate.

[rsanchez15]

It would be better to start with the structure of the project to understand why it is necessary to create a type for these two warnings. In the project I am documenting a C++ code with the following tools:

• Doxygen: for documentation of classes, methods, functions, etc. The comments are written in the following source code, doxygen style, and then parsed to xml files.
• Breathe: sphinx module to generate documentation in reStructuredText format from Doxygen's xml output.
• Sphinx: for the generation of the complete documentation of the project.

The following cases are presented in the project:

1. Several functions with the same declaration but different arguments. For example:

   inline bool operator ==(const MyStruct s1, const MyStruct& s2){...}
inline bool operator ==(const MySecondStruct s1, const MySecondStruct& s2){...}

   This raises the following warning: WARNING: Duplicate declaration.

2. Definition of const objects as follows:

struct Time_t
{
    int32_t seconds;
    uint32_t nanosec;
    ...
    Time_t(int32_t sec, uint32_t nsec);
}

...

const Time_t c_TimeZero(0,0);

The object declaration in this manner causes Doxygen to render it as a function and therefore Breathe must load it as a function (doxygenfunction directive), thus issuing the following warning:

<path/to/rst/file>:9: WARNING: Error when parsing function declaration.
If the function has no return type:
  Error in declarator or parameters-and-qualifiers
  Invalid C++ declaration: Expected identifier in nested name, got keyword: const [error at 5]
    const Time_t c_TimeZero (0, 0)
    -----^
If the function has a return type:
  Error in declarator or parameters-and-qualifiers
  If pointer to member declarator:
    Invalid C++ declaration: Expected '::' in pointer to member (function). [error at 44]
      const Time_t c_TimeZero (0, 0)
      ------------------------^
  If declarator-id:
    Invalid C++ declaration: Expected identifier in nested name. [error at 45]
      const Time_t c_TimeZero (0, 0)
      -------------------------^

It is important to mention that this pull request only adds the type and subtype to the warnings previously described to be able to suppress them, this is, it is not a functionality that will be executed for all users.

[jakobandersen]

I don't think either of those problems are in Sphinx.

1. Breathe spits out its own warnings as well. Do you have the exact full warning output? f you document these two functions in raw Sphinx there are no warnings.
2. This is a variable declaration. Something icky is going on in Breathe (or perhaps even Doxygen?) as it uses the wrong directive type.
   If not tried already, try with the newest version of Breathe, and if there are still icky warnings, then please open an issue (for each of these) over there to continue the discussion.

However, your example lead me to realize that even when changing the directive to a variable, there will be a problem, as the parenthesised initializer is not recognized. I'll get that fixed soon. Thanks.

[rsanchez15]

The source of the problems may not be Sphinx but that's where the warnings are triggered. So I think there should be some way to suppress certain specific warnings in sphinx. I know that this is already implemented (suppress_warnings) but only for certain very specific warnings. My intention is to provide two more types for the warnings classification.

1. The complete warning is as follows:

<path/to/rst/file>:<line>: WARNING: Duplicate declaration, bool operator== (const Time_t &t1, const Time_t &t2)

2. I'll do what you suggest.

[jakobandersen]

That is indeed a warning from Sphinx. While some other types of warnings are really more notices (e.g., those hidden in non-nitpicky mode), both the duplicate declaration and parsing warnings are symptoms some actual problems that should be addressed. I'll therefore close the PR.
As you are using Breathe I recommend opening issue for the duplicate declaration as well, with as much info as possible.