Add support for ADL-controlling namespaces

[akrzemi1]

There is an advice for libraries to introduce another intermedite namespace in order for a single type not to intercept every single function from your library:

namespace my_lib
{
  namespace x_guard
  {
    class X {};
    void f(X x) {} // ADL-discoverable interface of X
  }
  using x_guard::X;

  template <typename T>
  void g(T x) {} // unrelated function in the same library
}

int main()
{
  my_lib::X x{}; // almost as if X was directly in my_lib
  f(x); // works as designed
  g(x); // doesn't work, as intended
  my_lib::g(x); // works as intended
}

I don't know if there is a name for this pattern, so let's say that x_guard is an ADL-controlling namespace.
I use such ADL-controlling namespaces in my libraries: https://github.com/akrzemi1/markable/blob/master/include/ak_toolkit/markable.hpp#L721-L743
Could you add a configuration parmeter that hides a namespace x_guard from the user in the docs?

[alandefreitas]

If this is a widespread pattern, MrDocs needs to support it. The design and implementation of this option doesn't look so simple though.

[alandefreitas]

@vinniefalco any ideas on how this feature could be designed?

[vinniefalco]

This is a case where we have to be very careful interpreting what a user wants. Hiding a namespace seems to resolve the immediate problem in the short-term but does not sound like a good solution. The "ADL-controlling namespace" idiom is a workaround which should not be visible in the user documentation. The result of the workaround is to present X as-if it is part of my_lib in a way that inhibits ADL.

My first thought on how to accomplish this, is that we need to tell Mr. Docs that the idiom is in use. And then have a post-processing step adjust the metadata to reflect it. Maybe add a "IsADLDisabled" flag or something.

Hiding x_guard also creates a new problem. There will be no documentation emitted for f. And it is an open question where the javadoc for X will go. And, the current architecture might have a problem with a using statement for a namespace that is not extracted.