Add comprehensive examples to BC42328.md to improve understanding

docs/visual-basic/misc/bc42328.md

@@ -24,28 +24,15 @@ Visual Basic allows you to assign methods to delegates even when their signature
 
 ## When this warning occurs
 
-This warning appears when Visual Basic can handle the assignment through relaxed conversion, making the explicit `AddressOf` unnecessary. For example:
+This warning appears when Visual Basic can handle the assignment through relaxed conversion, making the explicit `AddressOf` unnecessary.
 
-```vb
-' Event delegate expects (sender As Object, e As EventArgs)
-Public Event SomeEvent As EventHandler
-
-' Method with exact signature - no warning
-Sub Handler1(sender As Object, e As EventArgs)
-    ' Implementation
-End Sub
+### Complete example showing the warning
 
-' Method with omitted parameters - causes BC42328
-Sub Handler2()
-    ' Implementation  
-End Sub
+The following example shows one scenario that produces BC42328:
 
-' Using AddHandler with exact match - no warning
-AddHandler SomeEvent, AddressOf Handler1
+:::code language="vb" source="snippets/bc42328/AddressOfExample.vb" id="DocumentProcessor":::
 
-' Using AddHandler with relaxed conversion - causes BC42328
-AddHandler SomeEvent, AddressOf Handler2
-```
+When you compile this code, Visual Basic shows the BC42328 warning for the `AddHandler` statements that use relaxed delegate conversion.
 
 ## Why AddressOf appears to have "no effect"
 
@@ -57,36 +44,80 @@ However, `AddressOf` is still syntactically required in `AddHandler` and `Remove
 
 ## To correct this error
 
-You have several options depending on your needs:
+You have several options depending on your needs. Using the `DocumentProcessor` example from previously, here are the different ways to resolve the BC42328 warning:
 
-- **Assign to a variable first (preserves exact semantics):**
+### Option 1: Assign to a variable first (preserves exact semantics)
 
-   ```vb
-   Dim handler As EventHandler = AddressOf Handler2
-   AddHandler SomeEvent, handler
-   ```
+```vb
+Public Sub DemonstrateHandler()
+    ' Create delegate variable first - this eliminates the warning
+    Dim handler As EventHandler = AddressOf OnDocumentProcessed_Simple
+    AddHandler DocumentProcessed, handler
+End Sub
+```
 
-- **Match the delegate signature exactly:**
+### Option 2: Match the delegate signature exactly
 
-   ```vb
-   Sub Handler2(sender As Object, e As EventArgs)
-       ' Implementation - use parameters or ignore them
-   End Sub
-  ```
+```vb
+' Change the method signature to match EventHandler exactly
+Private Sub OnDocumentProcessed_Simple(sender As Object, e As EventArgs)
+    ' You can ignore the parameters if you don't need them
+    Console.WriteLine("Document processed (simple)")
+End Sub
 
-- **Use a lambda expression:**
+Public Sub DemonstrateHandler()
+    ' Now this works without warning
+    AddHandler DocumentProcessed, AddressOf OnDocumentProcessed_Simple
+End Sub
+```
 
-   ```vb
-   AddHandler SomeEvent, Sub() Handler2()
-   ```
+### Option 3: Use a lambda expression
 
-- **Use the `Handles` clause if appropriate:**
+```vb
+Public Sub DemonstrateHandler()
+    ' Wrap the method call in a lambda that matches the signature
+    AddHandler DocumentProcessed, Sub(sender, e) OnDocumentProcessed_Simple()
+
+    ' Or create a more complex lambda inline
+    AddHandler DocumentProcessed, 
+        Sub(sender, e) 
+            Console.WriteLine($"Event from {sender}")
+            OnDocumentProcessed_Simple()
+        End Sub
+End Sub
+```
 
-   ```vb
-   Sub Handler2() Handles someObject.SomeEvent
-       ' Implementation
-   End Sub
-   ```
+### Option 4: Use the `Handles` clause (if appropriate)
+
+```vb
+Public Class DocumentHandler
+    ' Declare the event source with WithEvents
+    Private WithEvents processor As DocumentProcessor
+
+    ' Use Handles clause - no AddHandler needed
+    Private Sub OnDocumentComplete() Handles processor.DocumentProcessed
+        Console.WriteLine("Document processing is done!")
+    End Sub
+End Class
+```
+
+### Option 5: Direct assignment to delegate variable
+
+```vb
+Public Sub DemonstrateHandler()
+    ' Assign to delegate variable then use with AddHandler
+    Dim handler As EventHandler = AddressOf OnDocumentProcessed_Simple
+    AddHandler DocumentProcessed, handler
+End Sub
+```
+
+## Complete working example
+
+The following full example demonstrates the warning and multiple solutions:
+
+:::code language="vb" source="snippets/bc42328/AddressOfExample.vb":::
+
+This example shows how the warning occurs in realistic scenarios and demonstrates multiple ways to resolve it.
 
 ## When you can ignore this warning
 
@@ -95,8 +126,27 @@ This warning is often safe to ignore when:
 - Your handler method intentionally omits parameters it doesn't need.
 - You're using a simpler method signature for cleaner code.
 - The performance impact is negligible for your application.
+- You're prototyping or writing quick utility code where clarity matters more than efficiency.
+
+The relaxed conversion works correctly; this warning just indicates a minor efficiency consideration. The compiler creates a wrapper delegate automatically, which adds a small performance overhead but doesn't affect functionality.
 
-The relaxed conversion works correctly; this warning just indicates a minor efficiency consideration.
+### Example of when ignoring is appropriate
+
+```vb
+Public Class QuickLogger
+    Public Event LogMessage As Action(Of String, DateTime)
+
+    ' Simple handler that ignores the timestamp parameter
+    Private Sub WriteToConsole()
+        Console.WriteLine("Something was logged")
+    End Sub
+
+    Public Sub SetupLogging()
+        ' This generates BC42328, but it's fine for simple scenarios
+        AddHandler LogMessage, AddressOf WriteToConsole
+    End Sub
+End Class
+```
 
 ## See also
 

docs/visual-basic/misc/snippets/bc42328/AddressOfExample.vb

@@ -0,0 +1,84 @@
+Imports System
+
+' <DocumentProcessor>
+Public Class DocumentProcessor
+    ' Standard .NET event using EventHandler
+    Public Event DocumentProcessed As EventHandler
+
+    ' Custom event with different signature
+    Public Event StatusChanged As Action(Of String)
+
+    ' Handlers with different signatures
+
+    ' Exact match for EventHandler - no warning
+    Private Sub OnDocumentProcessed_Exact(sender As Object, e As EventArgs)
+        Console.WriteLine("Document processed (exact signature)")
+    End Sub
+
+    ' Simplified handler - causes BC42328 with EventHandler
+    Private Sub OnDocumentProcessed_Simple()
+        Console.WriteLine("Document processed (simple)")
+    End Sub
+
+    ' Handler for custom event - exact match
+    Private Sub OnStatusChanged_Exact(message As String)
+        Console.WriteLine($"Status: {message}")
+    End Sub
+
+    ' Handler with ignored parameters - causes BC42328 with custom event
+    Private Sub OnStatusChanged_Simple()
+        Console.WriteLine("Status changed")
+    End Sub
+
+    Public Sub DemonstrateWarnings()
+        Console.WriteLine("Setting up event handlers...")
+
+        ' These work without warnings (exact matches)
+        AddHandler DocumentProcessed, AddressOf OnDocumentProcessed_Exact
+        AddHandler StatusChanged, AddressOf OnStatusChanged_Exact
+
+        ' These generate BC42328 warnings (relaxed conversions)
+        AddHandler DocumentProcessed, AddressOf OnDocumentProcessed_Simple
+        AddHandler StatusChanged, AddressOf OnStatusChanged_Simple
+
+        ' Fire the events
+        RaiseEvent DocumentProcessed(Me, EventArgs.Empty)
+        RaiseEvent StatusChanged("Processing complete")
+    End Sub
+
+    Public Sub DemonstrateSolutions()
+        Console.WriteLine("Using solutions to avoid warnings...")
+
+        ' Solution 1: Assign to variable first
+        Dim handler1 As EventHandler = AddressOf OnDocumentProcessed_Simple
+        AddHandler DocumentProcessed, handler1
+
+        ' Solution 2: Use lambda expression
+        AddHandler DocumentProcessed, Sub(s, e) OnDocumentProcessed_Simple()
+
+        ' Solution 3: Direct assignment to delegate variable
+        Dim handler2 As Action(Of String) = AddressOf OnStatusChanged_Simple
+        AddHandler StatusChanged, handler2
+
+        ' Fire the events
+        RaiseEvent DocumentProcessed(Me, EventArgs.Empty)
+        RaiseEvent StatusChanged("All solutions work")
+    End Sub
+End Class
+' </DocumentProcessor>
+
+Module Program
+    Sub Main()
+        Dim processor As New DocumentProcessor()
+
+        Console.WriteLine("=== Demonstrating BC42328 Warning ===")
+        processor.DemonstrateWarnings()
+
+        Console.WriteLine()
+        Console.WriteLine("=== Demonstrating Solutions ===")
+        processor.DemonstrateSolutions()
+
+        Console.WriteLine("Press any key to exit...")
+        Console.ReadKey()
+    End Sub
+End Module

docs/visual-basic/misc/snippets/bc42328/AddressOfExample.vbproj

@@ -0,0 +1,9 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <RootNamespace>BC42328Example</RootNamespace>
+  </PropertyGroup>
+
+</Project>