add CA2265 docs

Author: gewarren

docs/fundamentals/code-analysis/quality-rules/ca2265.md

@@ -0,0 +1,61 @@
+---
+title: "CA2265: Do not compare Span<T> to 'null' or 'default'"
+description: "Learn about code analysis rule CA2265 - Do not compare Span<T> to 'null' or 'default'"
+ms.date: 10/28/2024
+f1_keywords:
+  - CA2265
+helpviewer_keywords:
+  - CA2265
+dev_langs:
+  - CSharp
+---
+# CA2265: Do not compare `Span<T>` to `null` or `default`
+
+| Property                            | Value                                           |
+|-------------------------------------|-------------------------------------------------|
+| **Rule ID**                         | CA2264                                          |
+| **Title**                           | Do not compare `Span<T>` to `null` or `default` |
+| **Category**                        | [Usage](usage-warnings.md)                      |
+| **Fix is breaking or non-breaking** | Non-breaking                                    |
+| **Enabled by default in .NET 9**    | As warning                                      |
+
+## Cause
+
+A <xref:System.Span`1> instance is compared to `null` or `default`.
+
+## Rule description
+
+Comparing a span to `null` or `default` might not do what you intended. `default` and the `null` literal are implicitly converted to `Span<T>.Empty`.
+
+## How to fix violations
+
+Remove the redundant comparison or make the code more explicit by calling <xref:System.Span`1.IsEmpty> instead.
+
+## Example
+
+The following code snippet shows two violations of CA2265 and the fix for the violations.
+
+:::code language="vb" source="snippets/vb/all-rules/ca2265.vb":::
+
+## When to suppress warnings
+
+It's safe to suppress this warning if you meant to compare the span to the empty span.
+
+## Suppress a warning
+
+If you just want to suppress a single violation, add preprocessor directives to your source file to disable and then re-enable the rule.
+
+```csharp
+#pragma warning disable CA2265
+// The code that's violating the rule is on this line.
+#pragma warning restore CA2265
+```
+
+To disable the rule for a file, folder, or project, set its severity to `none` in the [configuration file](../configuration-files.md).
+
+```ini
+[*.{cs,vb}]
+dotnet_diagnostic.CA2265.severity = none
+```
+
+For more information, see [How to suppress code analysis warnings](../suppress-warnings.md).

docs/fundamentals/code-analysis/quality-rules/index.md

@@ -237,6 +237,7 @@ The following table lists code quality analysis rules.
 > | [CA2262: Set `MaxResponseHeadersLength` properly](ca2262.md) | Make sure the `MaxResponseHeadersLength` value is provided correctly. This value is measured in kilobytes. |
 > | [CA2263: Prefer generic overload when type is known](ca2263.md) | Using a generic overload is preferable to passing a <xref:System.Type?displayProperty=fullName> argument when the type is known, because they promote cleaner and more type-safe code with improved compile-time checks. |
 > | [CA2264: Do not pass a non-nullable value to 'ArgumentNullException.ThrowIfNull'](ca2264.md) | 'ArgumentNullException.ThrowIfNull' throws when the passed argument is 'null'. Certain constructs like non-nullable structs, and 'nameof()' and 'new' expressions are known to never be null, so 'ArgumentNullException.ThrowIfNull' will never throw. |
+> | [CA2265: Do not compare `Span<T>` to `null` or `default`](ca2265.md) | Comparing a span to `null` or `default` might not do what you intended. `default` and the `null` literal are implicitly converted to `Span<T>.Empty`. |
 > | [CA2300: Do not use insecure deserializer BinaryFormatter](ca2300.md) | Insecure deserializers are vulnerable when deserializing untrusted data. An attacker could modify the serialized data to include unexpected types to inject objects with malicious side effects. |
 > | [CA2301: Do not call BinaryFormatter.Deserialize without first setting BinaryFormatter.Binder](ca2301.md) | Insecure deserializers are vulnerable when deserializing untrusted data. An attacker could modify the serialized data to include unexpected types to inject objects with malicious side effects. |
 > | [CA2302: Ensure BinaryFormatter.Binder is set before calling BinaryFormatter.Deserialize](ca2302.md) | Insecure deserializers are vulnerable when deserializing untrusted data. An attacker could modify the serialized data to include unexpected types to inject objects with malicious side effects. |

docs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/ca2265.cs

@@ -0,0 +1,19 @@
+using System;
+
+namespace ca2265;
+class CA2265
+{
+    public static void RunIt()
+    {
+        // <Snippet1>
+        Span<int> span = new([1, 2, 3]);
+        // CA2265 violation.
+        if (span == null) { }
+        // CA2265 violation.
+        if (span == default) { }
+
+        // Fixes the violation.
+        if (span.IsEmpty) { }
+        // </Snippet1>
+    }
+}

docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/all-rules.vbproj

@@ -3,7 +3,7 @@
   <PropertyGroup>
     <OutputType>Exe</OutputType>
     <RootNamespace>all_rules</RootNamespace>
-    <TargetFramework>net8.0</TargetFramework>
+    <TargetFramework>net9.0</TargetFramework>
     <NoWarn>$(NoWarn);SYSLIB0050</NoWarn>
   </PropertyGroup>
 

docs/fundamentals/code-analysis/quality-rules/usage-warnings.md

@@ -63,4 +63,5 @@ Usage rules support proper usage of .NET.
 | [CA2261: Do not use `ConfigureAwaitOptions.SuppressThrowing` with `Task<TResult>`](ca2261.md) | The `ConfigureAwaitOptions.SuppressThrowing` option isn't supported by the generic `Task<TResult>`, since that might lead to returning an invalid `TResult`. |
 | [CA2262: Set `MaxResponseHeadersLength` properly](ca2262.md) | Make sure the `MaxResponseHeadersLength` value is provided correctly. This value is measured in kilobytes. |
 | [CA2264: Do not pass a non-nullable value to 'ArgumentNullException.ThrowIfNull'](ca2264.md) | 'ArgumentNullException.ThrowIfNull' throws when the passed argument is 'null'. Certain constructs like non-nullable structs, and 'nameof()' and 'new' expressions are known to never be null, so 'ArgumentNullException.ThrowIfNull' will never throw. |
+| [CA2265: Do not compare `Span<T>` to `null` or `default`](ca2265.md) | Comparing a span to `null` or `default` might not do what you intended. `default` and the `null` literal are implicitly converted to `Span<T>.Empty`. |
 | [CA2263: Prefer generic overload when type is known](ca2263.md) | Using a generic overload is preferable to passing a <xref:System.Type?displayProperty=fullName> argument when the type is known, because they promote cleaner and more type-safe code with improved compile-time checks. |

docs/navigate/tools-diagnostics/toc.yml

@@ -1431,6 +1431,8 @@ items:
                     href: ../../fundamentals/code-analysis/quality-rules/ca2263.md
                   - name: CA2264
                     href: ../../fundamentals/code-analysis/quality-rules/ca2264.md
+                  - name: CA2265
+                    href: ../../fundamentals/code-analysis/quality-rules/ca2265.md
           - name: Code style rules
             items:
               - name: Overview