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

[Eric Li 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
----------------
tJener wrote:

I understood this as fully-qualifying the namespace when necessary to refer to the correct namespace. For example,

```c++
namespace other::foo {
a::A thing;
}  // namespace other::foo
namespace foo {
a::A thing;
}  // namespace foo
namespace other {
a::A thing;
struct foo {
  a::A thing;
};
a::A thing2;
}  // namespace other
```

becomes

```c++
namespace other::foo {
::foo::A thing;
}  // namespace other::foo
namespace foo {
A thing;
}  // namespace foo
namespace other {
foo::A thing;
struct foo {
  ::foo::A thing;
};
::foo:A thing2;
}  // namespace other
```

@kwk is that understanding correct?

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