Clarify using directive examples

Fixes #43136: Using directives can appear in namespace declarations, unless it's a global using.

Fixes #29746:  Add notes about how to get diagnostics on duplicated global usings, and considering a standard location for all global usings in a project.

Fixes #27331:  Rework a couple sentences for clarity.

Fixes #26469:  Add text an examples for the `::` token for qualified namespace aliases.

Author: BillWagner

docs/csharp/language-reference/keywords/snippets/UsingAliasQualifier.cs

@@ -0,0 +1,24 @@
+
+// <UsingAliasQualifier>
+using S = System.Net.Sockets;
+
+class A
+{
+    public static int x;
+}
+
+class C
+{
+    public void F(int A, object S)
+    {
+        // Use global::A.x instead of A.x
+        global::A.x += A;
+
+        // Using ::, S must resolve to a namespace alias:
+        S::Socket s = S as S::Socket;
+
+        // In this form, if S were a class, it would be a compile-time error:
+        S.Socket s1 = S as S.Socket;
+    }
+}
+// </UsingAliasQualifier>

docs/csharp/language-reference/keywords/using-directive.md

@@ -1,12 +1,11 @@
 ---
-description: "using directive - C# Reference"
-title: "using directive"
-ms.date: 08/19/2021
+description: "The `using` directive imports types from a namespace, or creates an alias for a given type. Using directives enable you to use simple names for types instead of the fully qualified type name."
+title: "The using directive: Import types from a namespace"
+ms.date: 11/14/2024
 f1_keywords:
   - "using_CSharpKeyword"
 helpviewer_keywords:
   - "using directive [C#]"
-ms.assetid: b42b8e61-5e7e-439c-bb71-370094b44ae8
 ---
 # using directive
 
@@ -21,7 +20,7 @@ You can apply two modifiers to a `using` directive:
 - The `global` modifier has the same effect as adding the same `using` directive to every source file in your project. This modifier was introduced in C# 10.
 - The `static` modifier imports the `static` members and nested types from a single type rather than importing all the types in a namespace.
 
-You can combine both modifiers to import the static members from a type in all source files in your project.
+You can combine both modifiers to import the static members from a type to all source files in your project.
 
 You can also create an alias for a namespace or a type with a *using alias directive*.
 
@@ -36,12 +35,14 @@ You can use the `global` modifier on a *using alias directive*.
 
 The scope of a `using` directive without the `global` modifier is the file in which it appears.
 
-The `using` directive can appear:
+The `global using` directive must appear before all namespace and type declarations. All global using directives must appear in a source file before any non-global `using` directives.
+
+Other `using` directives can appear:
 
 - At the beginning of a source code file, before any namespace or type declarations.
-- In any namespace, but before any namespaces or types declared in that namespace, unless the `global` modifier is used, in which case the directive must appear before all namespace and type declarations.
+- In any blocked-scoped namespace, but before any namespaces or types declared in that namespace.
 
-Otherwise, compiler error [CS1529](../compiler-messages/using-directive-errors.md) is generated.
+Otherwise, a compiler error is generated.
 
 Create a `using` directive to use the types in a namespace without having to specify the namespace. A `using` directive doesn't give you access to any namespaces that are nested in the namespace you specify. Namespaces come in two categories: user-defined and system-defined. User-defined namespaces are namespaces defined in your code. For a list of the system-defined namespaces, see [.NET API Browser](../../../../api/index.md).
 
@@ -70,6 +71,8 @@ global using static System.Math;
 
 You can also globally include a namespace by adding a `<Using>` item to your project file, for example, `<Using Include="My.Awesome.Namespace" />`. For more information, see [`<Using>` item](../../../core/project-sdk/msbuild-props.md#using).
 
+Analyzers issue diagnostics if you've duplicated `global` using directives in different locations. These same analyzers also inform you if you add a `using` directive for a namespace or type that is already referenced by a `global` using directive. You might find it easier to manage your `global` usings by keeping them together in one file in the project.
+
 [!INCLUDE [csharp10-templates](../../../../includes/csharp10-templates.md)]
 
 ## static modifier
@@ -160,6 +163,14 @@ The following example shows how to define a `using` directive and a `using` alia
 
 Beginning with C# 12, you can create aliases for types that were previously restricted, including [tuple types](../builtin-types/value-tuples.md#tuple-field-names), pointer types, and other unsafe types. For more information on the updated rules, see the [feature spec](~/_csharplang/proposals/csharp-12.0/using-alias-types.md).
 
+## Qualified alias member
+
+The namespace alias qualifier, `::` provides explicit access to the global namespace or other using aliases that are potentially hidden by other entities.
+
+The `global::` ensures that the namespace lookup for the namespace to the right of the `::` token is relative to the global namespace. Otherwise, the token must resolve to a using alias, and the token to the right must resolve to a type in that aliased namespace. The following example shows both forms:
+
+:::code language="csharp" source="./snippets/UsingAliasQualifier.cs" id="UsingAliasQualifier":::
+
 ## C# language specification
 
 For more information, see [Using directives](~/_csharpstandard/standard/namespaces.md#145-using-directives) in the [C# Language Specification](~/_csharpstandard/standard/README.md). The language specification is the definitive source for C# syntax and usage.