Clarify what constitutes a type conflict in CS0436 compiler warning documentation (#48863)

* Initial plan

* Clarify what constitutes a conflict in CS0436 documentation

Co-authored-by: BillWagner <[email protected]>

* Apply suggestions from code review

Co-authored-by: Meaghan Osagie (Lewis) <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: BillWagner <[email protected]>
Co-authored-by: Bill Wagner <[email protected]>
Co-authored-by: Meaghan Osagie (Lewis) <[email protected]>

Author: 3 people

docs/csharp/misc/cs0436.md

@@ -1,7 +1,7 @@
 ---
 description: "Compiler Warning (level 2) CS0436"
 title: "Compiler Warning (level 2) CS0436"
-ms.date: 07/20/2015
+ms.date: 10/01/2025
 f1_keywords: 
   - "CS0436"
 helpviewer_keywords: 
@@ -12,9 +12,23 @@ ms.assetid: c4135d9d-3511-4bbc-9540-48c2091f869c
 
 The type 'type' in 'assembly' conflicts with the imported type 'type2' in 'assembly'. Using the type defined in 'assembly'.  
 
- This warning is issued when a type in a source file (file_2) conflicts with an imported type in file_1. The compiler uses the one in the source file.  
+This warning occurs when a type defined in your source code has the same fully qualified name (namespace and type name) as a type imported from a referenced assembly. When this name conflict occurs, the compiler uses the locally defined type from your source file and ignores the imported type.
+
+## What constitutes a conflict
+
+A conflict occurs when two types have identical fully qualified names, meaning:
+
+- They have the same namespace
+- They have the same type name
+- They're both accessible in the current compilation context
+
+The conflict is determined solely by the type's fully qualified name, not by its implementation details. Two types with the same name but different implementations (such as different methods, properties, or field values) still conflict. The compiler can't use both types simultaneously because they have the same identity.  
 
-## Example 1
+## Example
+
+The following example demonstrates CS0436. In this scenario, a type `A` is defined in an external library and also locally in the source file. Even though the two types have different implementations (they print different strings), they conflict because they share the same fully qualified name.
+
+First, create a library that defines type `A`:
 
 ```csharp  
 // CS0436_a.cs  
@@ -26,10 +40,8 @@ public class A {
 }  
 ```  
 
-## Example 2  
+Then, compile the following code that defines another type `A` and references the library. The compiler issues CS0436 because both types have the fully qualified name `A` (in the global namespace):
 
- The following example generates CS0436.  
-  
 ```csharp  
 // CS0436_b.cs  
 // compile with: /reference:CS0436_a.dll  
@@ -39,7 +51,7 @@ public class A {
       System.Console.WriteLine("CS0436_b");  
    }  
 }  
-  
+
 public class Test
 {  
    public static void Main()
@@ -50,8 +62,19 @@ public class Test
 }  
 ```
 
-Compilation produces the following output:
+When you compile and run this code, the compiler uses the locally defined `A` (from CS0436_b.cs) and issues a warning. The output is:
 
 ```console
 CS0436_b
 ```
+
+Note that the conflict exists even though the two `A` types have different implementations. The difference in the string literal (`"CS0436_a"` versus `"CS0436_b"`) doesn't prevent the conflict. What matters is that both types have the same fully qualified name `A`.
+
+## How to resolve this warning
+
+To resolve this warning, you can:
+
+1. Rename one of the conflicting types.
+1. Use a different namespace for one of the types.
+1. Remove the reference to the assembly containing the conflicting type if it's not needed.
+1. Use an extern alias to disambiguate between the two types if you need to use both (see [CS0433](/dotnet/csharp/language-reference/compiler-messages/cs0433) for examples of using extern aliases).