Diagnose for invalid decl nesting + namespace lookup fixes. (#3397)

* Diagnose for invalid decl nesting.

* Fix.

* Fix.

* Fix.

* Fix `namespace` lookup and `using` resolution.

* fix project files.

* revert project files.

* Enhance namespace syntax, docs.

* Fixes.

---------

Co-authored-by: Yong He <yhe@nvidia.com>

2 files changed, 63 insertions, 0 deletions

diff --git a/docs/user-guide/03-convenience-features.md b/docs/user-guide/03-convenience-features.md
index 74676699f..4957f267e 100644
--- a/docs/user-guide/03-convenience-features.md
+++ b/docs/user-guide/03-convenience-features.md
@@ -35,6 +35,68 @@ let a = 5;
 a = 6; // Error, `a` is immutable.
 ```
 
+
+## Namespaces
+
+You can use the `namespace` syntax to define symbols in a namespace:
+```csharp
+namespace ns
+{
+    int f();
+}
+```
+
+Slang also supports the abbreviated syntax for defining nested namespaces:
+```csharp
+namespace ns1.ns2
+{
+    int f();
+}
+// equivalent to:
+namespace ns1::ns2
+{
+    int f();
+}
+// equivalent to:
+namespace ns1
+{
+    namespace ns2
+    {
+        int f();
+    }
+}
+```
+
+To access symbols defined in a namespace, you can use its qualified name with namespace prefixes:
+```csharp
+void test()
+{
+    ns1.ns2.f();
+    ns1::ns2::f(); // equivalent syntax.
+}
+```
+
+Symbols defined in the same namespace can access each other without a qualified name, this is true even if the referenced symbol is defined in a different file or module:
+```csharp
+namespace ns
+{
+    int f();
+    int g() { f(); } // OK.
+}
+```
+
+You can also use the `using` keyword to pull symbols defined in a different namespace to
+the current scope, removing the requirement for using fully qualified names.
+```csharp
+namespace ns1.ns2
+{
+    int f();
+}
+
+using ns1.ns2;
+void test() { f(); } // OK.
+```
+
 ## Member functions
 
 Slang supports defining member functions in `struct`s. For example, it is allowed to write:
diff --git a/docs/user-guide/toc.html b/docs/user-guide/toc.html
index 5f8a9d46a..1533d3655 100644
--- a/docs/user-guide/toc.html
+++ b/docs/user-guide/toc.html
@@ -31,6 +31,7 @@
 <ul class="toc_list">
 <li data-link="03-convenience-features#type-inference-in-variable-definitions"><span>Type Inference in Variable Definitions</span></li>
 <li data-link="03-convenience-features#immutable-values"><span>Immutable Values</span></li>
+<li data-link="03-convenience-features#namespaces"><span>Namespaces</span></li>
 <li data-link="03-convenience-features#member-functions"><span>Member functions</span></li>
 <li data-link="03-convenience-features#properties"><span>Properties</span></li>
 <li data-link="03-convenience-features#initializers"><span>Initializers</span></li>