Final proofread

Author: BillWagner

docs/csharp/language-reference/compiler-messages/new-and-object-creation-errors.md

@@ -40,7 +40,7 @@ That's by design. The text closely matches the text of the compiler error / warn
 - [**CS8753**](#target-typed-new-expressions): *Use of new() is not valid in this context*
 - [**CS8754**](#target-typed-new-expressions): *There is no target type for 'expression'*
 
-## Types that cannot be instantiated
+## Types that can't be instantiated
 
 - **CS0144**: *Cannot create an instance of the abstract type or interface 'type'*
 - **CS0712**: *Cannot create an instance of the static class 'type'*

docs/csharp/language-reference/compiler-messages/source-generator-errors.md

@@ -150,6 +150,44 @@ The following warnings occur when the compiler loads source generators or interc
 
 These errors and warnings follow these themes:
 
+## Source generator failures
+
+- **CS8784**: *Generator 'generator' failed to initialize. It will not contribute to the output and compilation errors may occur as a result. Exception was of type 'exception' with message 'message'.*
+- **CS8785**: *Generator 'generator' failed to generate source. It will not contribute to the output and compilation errors may occur as a result. Exception was of type 'exception' with message 'message'.*
+
+These warnings indicate that a source generator threw an unhandled exception during compilation. Source generators run as part of the build pipeline, and a failure prevents the generator from contributing its output to the compilation. For more information about implementing source generators, see [Source Generators](../../roslyn-sdk/source-generators-overview.md).
+
+To correct these warnings, follow this guidance:
+
+- Examine the full exception details in the build output to identify the root cause (**CS8784**, **CS8785**). The warning message includes the exception type, message, and stack trace, which can help you or the generator author diagnose the failure.
+- Ensure all required dependencies for the source generator are available in the project (**CS8784**). Initialization failures often occur when the generator can't locate a required assembly or resource during startup. Verify that the generator's NuGet package is correctly installed and all transitive dependencies are resolved.
+- Report the failure to the source generator's maintainer if the exception originates in third-party generator code (**CS8784**, **CS8785**). Include the full exception details from the build output in your bug report.
+- If you authored the source generator, add exception handling within your `Initialize` or `Execute` methods to catch and report errors gracefully (**CS8784**, **CS8785**).
+
+## Analyzer and source generator compatibility
+
+- **CS8032**: *An instance of analyzer 'analyzer' cannot be created from 'assembly' : 'reason'.*
+- **CS8033**: *The assembly 'assembly' does not contain any analyzers.*
+- **CS8034**: *Unable to load Analyzer assembly 'assembly' : 'reason'*
+- **CS8040**: *Skipping some types in analyzer assembly 'assembly' due to a ReflectionTypeLoadException : 'exception'.*
+- **CS8700**: *Multiple analyzer config files cannot be in the same directory ('directory').*
+- **CS8850**: *The assembly 'assembly' containing type 'type' references .NET Framework, which is not supported.*
+- **CS9057**: *Analyzer assembly 'assembly' cannot be used because it references version 'version' of the compiler, which is newer than the currently running version 'currentVersion'.*
+- **CS9067**: *Analyzer reference 'reference' specified multiple times*
+
+These warnings and errors indicate problems with loading, instantiating, or configuring analyzer and source generator assemblies. Because source generators load as analyzer assemblies, these diagnostics apply to both analyzers and source generators.
+
+To correct these problems, follow this guidance:
+
+- Upgrade your .NET SDK or compiler version to match the analyzer's requirements, or use an older version of the analyzer package that is compatible with your current compiler (**CS9057**). This error occurs when an analyzer assembly targets a newer Roslyn API version than the running compiler provides.
+- Remove duplicate analyzer references from your project (**CS9067**). Check your project file for repeated `<Analyzer>` or `<PackageReference>` elements that include the same analyzer assembly through different paths. Transitive package dependencies can also cause duplicates.
+- Verify the analyzer assembly is a valid .NET assembly and isn't corrupted (**CS8034**). If the assembly can't be loaded at all, ensure the file exists at the referenced path and was built for a compatible target framework. Rebuild or reinstall the NuGet package to get a fresh copy.
+- Ensure the analyzer type has a public parameterless constructor (**CS8032**). The compiler instantiates analyzers by calling their default constructor. If the constructor throws an exception or requires parameters, the analyzer can't be created.
+- Verify the referenced assembly actually exports analyzer or source generator types (**CS8033**). An assembly referenced as an analyzer must contain types that implement `DiagnosticAnalyzer` or `ISourceGenerator`/`IIncrementalGenerator`. If the assembly is a runtime dependency rather than an analyzer, reference it as a normal project or package reference instead.
+- Resolve type loading problems in the analyzer assembly by ensuring all its dependencies are available (**CS8040**). A `ReflectionTypeLoadException` typically means the assembly references types from other assemblies that can't be found. Make sure all required dependencies are included in the analyzer's NuGet package.
+- Ensure analyzer config files (`.editorconfig` or `.globalconfig`) are unique per directory (**CS8700**). The compiler doesn't allow multiple analyzer configuration files in the same directory because the precedence rules would be ambiguous. Merge the files or remove the duplicate.
+- Update the analyzer or source generator to target .NET Standard or modern .NET instead of .NET Framework (**CS8850**). Assemblies that reference .NET Framework aren't supported in the modern .NET compiler toolchain. If you maintain the analyzer, retarget it to `netstandard2.0`. If it's a third-party package, upgrade to a version that supports modern .NET.
+
 ## Interceptors are experimental
 
 - **CS9137**: *The 'interceptors' feature is not enabled in this namespace. Add `<Features>InterceptorsPreview</Features>` to your project.*
@@ -180,7 +218,7 @@ To correct these issues, ensure your interceptor method matches the interceptabl
 - Ensure the interceptor method signature exactly matches the interceptable method (**CS9144**, **CS9154**). The parameter types, modifiers, order, and return type must be identical. Review both method declarations and align their signatures.
 - Add a `this` parameter to your interceptor when the interceptable method is an instance method (**CS9148**), or remove the `this` parameter when the interceptable method is static (**CS9149**). Instance interceptors require a `this` parameter of the declaring type, while static interceptors must not have one.
 - Declare your interceptor in a location where the interceptable method is accessible (**CS9155**). If the interceptable method is `internal`, the interceptor must be in the same assembly. If it's `private`, the interceptor must be in the same type or a nested type.
-- Match the `scoped` modifiers and `[UnscopedRef]` attributes on corresponding `ref` parameters (**CS9156**). Each `ref` parameter in the interceptor must have the same lifetime annotations as the corresponding parameter in the interceptable method to ensure memory safety.
+- Match the [`scoped`](../statements/declarations.md#scoped-ref) modifiers and [`[UnscopedRef]`](../attributes/general.md#unscopedref-attribute) attributes on corresponding `ref` parameters (**CS9156**). Each `ref` parameter in the interceptor must have the same lifetime annotations as the corresponding parameter in the interceptable method to ensure memory safety.
 - Ensure both methods have matching generic arity (**CS9177**, **CS9178**). If the interceptable method is non-generic, the interceptor must also be non-generic. If the interceptable method has type parameters, the interceptor must have the same number of type parameters with compatible constraints.
 - Match the nullability annotations in the return type (**CS9158**) and parameter types (**CS9159**). Enable nullable reference types in your project and ensure the interceptor's nullability annotations match the interceptable method exactly to maintain type safety.
 - Use the updated `InterceptableLocation`-based generation for `InterceptsLocationAttribute` instead of the deprecated `(string, int, int)` constructor (**CS9270**). The newer format provides better tooling support and compile-time validation. See the [GitHub issue](https://github.com/dotnet/roslyn/issues/72133) for migration guidance.
@@ -241,41 +279,3 @@ To correct interceptor declaration errors, follow these rules for valid intercep
 - Remove `UnmanagedCallersOnlyAttribute` from interceptors (**CS9161**). Interceptors must be callable from managed code and can't be marked with `UnmanagedCallersOnlyAttribute`. Remove the attribute from your interceptor method declaration.
 - Declare interceptors within a namespace (**CS9206**). Interceptors can't be declared in the global namespace and must be contained within at least one namespace declaration. Wrap your interceptor class in a namespace.
 - Resolve duplicate file paths at the compilation level (**CS9152**). When multiple files share the same path in the compilation, the compiler can't determine which file to intercept. Ensure build configuration produces unique file paths or use a different organization strategy for your source files.
-
-## Source generator failures
-
-- **CS8784**: *Generator 'generator' failed to initialize. It will not contribute to the output and compilation errors may occur as a result. Exception was of type 'exception' with message 'message'.*
-- **CS8785**: *Generator 'generator' failed to generate source. It will not contribute to the output and compilation errors may occur as a result. Exception was of type 'exception' with message 'message'.*
-
-These warnings indicate that a source generator threw an unhandled exception during compilation. Source generators run as part of the build pipeline, and a failure prevents the generator from contributing its output to the compilation. For more information about implementing source generators, see [Source Generators](../../roslyn-sdk/source-generators-overview.md).
-
-To correct these warnings, follow this guidance:
-
-- Examine the full exception details in the build output to identify the root cause (**CS8784**, **CS8785**). The warning message includes the exception type, message, and stack trace, which can help you or the generator author diagnose the failure.
-- Ensure all required dependencies for the source generator are available in the project (**CS8784**). Initialization failures often occur when the generator can't locate a required assembly or resource during startup. Verify that the generator's NuGet package is correctly installed and all transitive dependencies are resolved.
-- Report the failure to the source generator's maintainer if the exception originates in third-party generator code (**CS8784**, **CS8785**). Include the full exception details from the build output in your bug report.
-- If you authored the source generator, add exception handling within your `Initialize` or `Execute` methods to catch and report errors gracefully (**CS8784**, **CS8785**).
-
-## Analyzer and source generator compatibility
-
-- **CS8032**: *An instance of analyzer 'analyzer' cannot be created from 'assembly' : 'reason'.*
-- **CS8033**: *The assembly 'assembly' does not contain any analyzers.*
-- **CS8034**: *Unable to load Analyzer assembly 'assembly' : 'reason'*
-- **CS8040**: *Skipping some types in analyzer assembly 'assembly' due to a ReflectionTypeLoadException : 'exception'.*
-- **CS8700**: *Multiple analyzer config files cannot be in the same directory ('directory').*
-- **CS8850**: *The assembly 'assembly' containing type 'type' references .NET Framework, which is not supported.*
-- **CS9057**: *Analyzer assembly 'assembly' cannot be used because it references version 'version' of the compiler, which is newer than the currently running version 'currentVersion'.*
-- **CS9067**: *Analyzer reference 'reference' specified multiple times*
-
-These warnings and errors indicate problems with loading, instantiating, or configuring analyzer and source generator assemblies. Because source generators load as analyzer assemblies, these diagnostics apply to both analyzers and source generators.
-
-To correct these problems, follow this guidance:
-
-- Upgrade your .NET SDK or compiler version to match the analyzer's requirements, or use an older version of the analyzer package that is compatible with your current compiler (**CS9057**). This error occurs when an analyzer assembly targets a newer Roslyn API version than the running compiler provides.
-- Remove duplicate analyzer references from your project (**CS9067**). Check your project file for repeated `<Analyzer>` or `<PackageReference>` elements that include the same analyzer assembly through different paths. Transitive package dependencies can also cause duplicates.
-- Verify the analyzer assembly is a valid .NET assembly and isn't corrupted (**CS8034**). If the assembly can't be loaded at all, ensure the file exists at the referenced path and was built for a compatible target framework. Rebuild or reinstall the NuGet package to get a fresh copy.
-- Ensure the analyzer type has a public parameterless constructor (**CS8032**). The compiler instantiates analyzers by calling their default constructor. If the constructor throws an exception or requires parameters, the analyzer can't be created.
-- Verify the referenced assembly actually exports analyzer or source generator types (**CS8033**). An assembly referenced as an analyzer must contain types that implement `DiagnosticAnalyzer` or `ISourceGenerator`/`IIncrementalGenerator`. If the assembly is a runtime dependency rather than an analyzer, reference it as a normal project or package reference instead.
-- Resolve type loading problems in the analyzer assembly by ensuring all its dependencies are available (**CS8040**). A `ReflectionTypeLoadException` typically means the assembly references types from other assemblies that can't be found. Make sure all required dependencies are included in the analyzer's NuGet package.
-- Ensure analyzer config files (`.editorconfig` or `.globalconfig`) are unique per directory (**CS8700**). The compiler doesn't allow multiple analyzer configuration files in the same directory because the precedence rules would be ambiguous. Merge the files or remove the duplicate.
-- Update the analyzer or source generator to target .NET Standard or modern .NET instead of .NET Framework (**CS8850**). Assemblies that reference .NET Framework aren't supported in the modern .NET compiler toolchain. If you maintain the analyzer, retarget it to `netstandard2.0`. If it's a third-party package, upgrade to a version that supports modern .NET.