add methods for dealing with C++ namespaces

Author: thewilsonator

spec/cpp_interface.dd

@@ -178,6 +178,88 @@ void main()
 }
 ------
 
+    $(P C++ can open the same namespace in the same file and multiple files.
+      In D, this can be done as follows:)
+
+---
+module ns;
+extern (C++, `ns`)
+{
+    int foo() { return 1; }
+    int bar() { return 2; }
+}
+---
+
+$(P or in multiple files, by organizing them in a package consisting of several modules:)
+---
+ns/
+|-- a.d
+|-- b.d
+|-- package.d
+---
+
+$(P File `ns/a.d`:)
+---
+module a; extern (C++, `ns`) { int foo() { return 1; } }
+---
+
+$(P File `ns/b.d`:)
+---
+module b; extern (C++, `ns`) { int bar() { return 2; } }
+---
+
+$(P File `ns/package.d`:)
+---
+module ns;
+public import a, b;
+---
+$(P Then you can import the package containing the extern C++ declarations as follows:)
+
+---
+import ns;
+static assert(foo() == 1 && bar() == 2);
+---
+
+$(P Note that the `extern (C++, `ns`)` linkage attribute affects only the ABI (name mangling and calling convention) of
+  these declarations. Importing them follows the usual
+  $(LINK2 spec/module, D module import semantics).)
+
+$(P Alternatively, the non-string form can be used to introduce a scope. Note that the
+    enclosing module already provides a scope for the symbols declared in the namespace.
+    This form does not allow closing and reopening the same namespace with in the same module. That is:)
+---
+module a; extern (C++, ns1) { int foo() { return 1; } }
+---
+---
+module b; extern (C++, ns1) { int bar() { return 2; } }
+---
+---
+import a, b;
+static assert(foo() == 1 && bar() == 2);
+---
+   $(P works, but:)
+---
+extern (C++, ns1) { int foo() { return 1; } }
+extern (C++, ns1) { int bar() { return 2; } }
+---
+   $(P does not. Additionally, aliases can be used to avoid collision of symbols:)
+---
+module a; extern (C++, ns) { int foo() { return 1; } }
+---
+---
+module b; extern (C++, ns) { int bar() { return 2; } }
+---
+---
+module ns;
+import a, b;
+alias foo = a.ns.foo;
+alias bar = b.ns.bar;
+---
+---
+import ns;
+static assert(foo() == 1 && bar() == 2);
+---
+
 $(H2 $(LNAME2 classes, Classes))
 
     $(P C++ classes can be declared in D by using the $(CODE extern (C++))