[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 tried running the binary and after looking at the tests, I believe I've misunderstood. It looks like the tool only changes symbol references _within the moved namespace_. It does _not_ update any symbol references from outside the moved namespace that point to symbols inside the moved namespace (which would no longer reference a valid symbol after the changes are applied).

Concrete example:
```c++
// a.cc
namespace old {
struct foo {};
}  // namespace old

namespace b {
old::foo g_foo;
}  // namespace b
```

```
$ clang-change-namespace --old_namespace 'old' --new_namespace 'new' --file_pattern '.*' a.cc
Error while trying to load a compilation database:
Could not auto-detect compilation database for file "a.cc"
No compilation database found in /tmp or any parent directory
fixed-compilation-database: Error while opening fixed database: No such file or directory
json-compilation-database: Error while opening JSON database: No such file or directory
Running without flags.
================= a.cc ================


namespace new {
  struct foo {};
} // namespace new

namespace b {
old::foo g_foo;
}  // namespace b

============================================
```

I think that is worth clarifying that this only updates symbol references in the moved namespace. (Unfortunately, I feel like that makes this tool much less useful.)

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