[clang-tools-extra] [doc] Add documentation for clang-change-namespace (PR #148277)

[Konrad Kleine via cfe-commits]

================
@@ -0,0 +1,155 @@
+======================
+Clang-Change-Namespace
+======================
+
+.. contents::
+
+.. toctree::
+  :maxdepth: 1
+
+:program:`clang-change-namespace` can be used to change the surrounding
+namespaces of class/function definitions.
+
+Classes/functions in the moved namespace will have new namespaces while
+references to symbols (e.g. types, functions) which are not defined in the
+changed namespace will be correctly qualified by prepending namespace specifiers
+before them. This will try to add shortest namespace specifiers possible.
+
+When a symbol reference needs to be fully-qualified, this adds a `::` prefix to
+the namespace specifiers unless the new namespace is the global namespace. For
----------------
kwk wrote:

> Perhaps not a question on the documentation, but rather the tool. Why is the global namespace special in this regard? It seems like there could be name ambiguities that arise with moving to the global namespace.

Consider this example to showcase ambiguities in names being used more than once:

```c++
cat test.cc 
namespace a {
class A {
  int classAFromWithinNamespace_a;
};
} // namespace a

class A {
  int classAInGlobalNamespace;
};
```

Then run `clang-change-namespace --old_namespace "a" --new_namespace "" --file_pattern test.cc test.cc` and the result will look like this:

```c++
class A {
  int classAFromWithinNamespace_a;
};

class A {
  int classAInGlobalNamespace;
};
```

The re-factoring looks correct but the code will not compile due to the name duplication. I'd say it is not up to the tool to ensure compilability in that sense. Of course, if you agree to this, then this MUST be documented.

https://github.com/llvm/llvm-project/pull/148277