Fix include/exclude options precedence

[alandefreitas]

It is supposed to work like this:

1. the user lists the namespaces they want extracted. For Boost libraries, this is usually boost::${LIB}.
2. the user lists the namespaces they want excluded. For Boost libraries, this is usually boost::${LIB}::detail.
3. The user optionally chooses namespaces to use for implementation-defined and see-below.

[anarthal]

I'm slightly confused with the current symbol filtering. In my ideal world, I'd like to include symbols in the boost::mysql namespace only, and nothing else. If I could have written include-namespaces: ['boost::mysql'], with MrDocs erroring if the given namespace is not there or is not a namespace, it'd be enough.

I strongly prefer whitelisting over blacklisting (and I'd say it's regarded as a better practice, in general). Some things I've tried that have generated confusion for me (ssl_mode here is a simple enumeration with no dependencies, any_connection is a big class with many dependencies):

1. Exclude everything, include a single entity:

filters:
  symbols:
    exclude:
      - '*'
    include:
      - 'boost::mysql::ssl_mode'

Expected: generates symbols for ssl_mode and its enumerators. Actual: generates all symbols in boost::mysql, boost::mysql::detail, other Boost libraries and some std constructs.

2. Play with referenced-declarations and other config options to set them to the most restrictive options:

filters:
  symbols:
    exclude:
      - 'boost::mysql::*'
    include:
      - 'boost::mysql::ssl_mode'
referenced-declarations: never
inaccessible-members: never
inaccessible-bases: never

Expected: same as before. Actual: most of the symbols are trimmed, but some are still generated in the asio and system namespaces. The generated symbols seem to be related to template specializations relating foreign namespaces.

3. Exclude all namespaces, and explicitly list what I want:

filters:
  symbols:
    exclude:
      - 'boost::*'
      - 'boost::mysql::*'
    include:
      - 'boost::mysql::ssl_mode'

This actually does what I want, but I need to include entities one by one.

4. Try to play with referenced-declarations:

filters:
  symbols:
    exclude:
      - 'boost::*'
      - 'boost::mysql::*'
    include:
      - 'boost::mysql::any_connection'
referenced-declarations: dependency

Expected: any_connection is generated, along with entities my class depends on, like connect_params. Actual: only any_connection is generated.

5. Blacklist what I don't want:

filters:
  symbols:
    exclude:
      - 'boost::system::*'
      - 'boost::asio::*'
      - 'boost::mysql::detail::*'
referenced-declarations: never

Expected: all entities in boost::mysql are listed. All the libraries I forgot to include in the blacklist, like Boost.Variant2, are generated. No docs are generated for boost::system or boost::asio. Actual: libraries I forgot to include there don't seem to be listed there (I'd expect things like boost::variant2, which are included, to be there). Pages are generated for the boost::asio and boost::system namespaces, although they're empty. This last approach mostly works, but it seems very brittle.

6. Some further tests to try to understand how globbing works:

filters:
  symbols:
    exclude:
      - '*'
      - 'boost::system::*'
      - 'boost::asio::*'
      - 'boost::mysql::detail::*'
referenced-declarations: never
inaccessible-members: never
inaccessible-bases: never

Expected: everything is excluded. Actual: this is equivalent to 5.

[anarthal]

Also, I'd expect inaccessible-members: never and inaccessible-bases: never to be the default. I don't think anyone wants to list their private members as if they were part of the interface, as they're, well, private. I know Doxygen tends to do things like that, but I don't think it's a good default.

[anarthal]

Regarding docs:

• I'd like to know the exact definition of what a wildcard is in this context. Does '*' match sub-namespaces? If it doesn't, is '**' a thing? If it does, why not use a regular regular expression?
• referenced-declarations uses the term "external declarations", which is never defined in the documentation. I understood it as "entities appearing in the public interface of matched symbols", but it looks like it's a different thing, according to the experiments above.

In general, I'd advocate for simplicity, as the current system looks pretty complex.