DP44/enriched-qwen3-coder-next/Common/DTS.Common.CPU/Properties.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.CPU/Properties/AssemblyInfo.cs Common/DTS.Common.CPU/Properties/Annotations.cs	2026-04-16T03:29:08.777780+00:00	Qwen/Qwen3-Coder-Next-FP8	1	2ecad58ebc9f0db4

Properties

Documentation: DTS.Common.CPU.Annotations Namespace

1. Purpose

This module provides a comprehensive set of JetBrains-style code annotation attributes for use in static analysis (e.g., by ReSharper or Rider) to improve nullability, contract, and usage intent expressiveness in C# code. It does not contain executable logic or business functionality; rather, it serves as a metadata layer to guide compiler/tooling behavior and human understanding of API contracts. The attributes are applied via attributes on types, methods, parameters, and properties to convey semantic constraints (e.g., nullability, immutability, usage patterns) that static analyzers interpret to generate warnings or suggestions.

2. Public Interface

All types reside in the DTS.Common.CPU.Annotations namespace. All attributes are sealed and inherit from Attribute. Below are the key public types:

Core Nullability Annotations

• CanBeNullAttribute
  Indicates the marked element may be null. Applies to methods, parameters, properties, fields, events, delegates, classes, interfaces, and generic parameters.
• NotNullAttribute
  Indicates the marked element must never be null. Applies to the same targets as CanBeNullAttribute.
• ItemCanBeNullAttribute
  For IEnumerable<T>, Task<T>, or Lazy<T>: indicates the item/result/value may be null.
• ItemNotNullAttribute
  For IEnumerable<T>, Task<T>, or Lazy<T>: indicates the item/result/value is guaranteed non-null.
• ImplicitNotNullAttribute
  Applies to types or assemblies: implicitly enforces [NotNull]/[ItemNotNull] on all members within scope.

Contract & Behavior Annotations

• StringFormatMethodAttribute(string formatParameterName)
  Marks a method as building a string from a format string (like string.Format). formatParameterName specifies which parameter holds the format string.
• ValueProviderAttribute(string name)
  Indicates a parameter/property/field must be one of a limited set of values, defined by fields of the type specified by name.
• InvokerParameterNameAttribute
  For parameters expected to be string literals matching a caller’s parameter name (e.g., ArgumentNullException parameter).
• NotifyPropertyChangedInvocatorAttribute(string parameterName = null)
  Marks methods used to notify property changes (e.g., INotifyPropertyChanged). Supports NotifyChanged(string), NotifyChanged(params string[]), expression-based overloads, and SetProperty patterns.
• ContractAnnotationAttribute(string contract, bool forceFullStates = false)
  Declares input-output dependencies (e.g., "s:null => true", "null => null; notnull => notnull"). Supports multiple instances per method.
• MustUseReturnValueAttribute(string justification = null)
  Indicates the return value of a method must be used.
• PureAttribute
  Indicates the method has no observable side effects (like System.Diagnostics.Contracts.PureAttribute).
• InstantHandleAttribute
  For delegate/IEnumerable parameters: indicates the parameter is used immediately within the method (e.g., executed or enumerated synchronously).
• ProvidesContextAttribute
  Marks a member as the canonical source for a context value (e.g., a service instance).
• CollectionAccessAttribute(CollectionAccessType type)
  Describes how a method/constructor/property affects a collection’s content. CollectionAccessType values:
  • None (0)
  • Read (1)
  • ModifyExistingContent (2)
  • UpdatedContent (7 = ModifyExistingContent | 4)
• AssertionMethodAttribute + AssertionConditionAttribute(AssertionConditionType)
  Marks assertion methods (e.g., Guard.NotNull). AssertionConditionType values: IS_TRUE, IS_FALSE, IS_NULL, IS_NOT_NULL.
• LinqTunnelAttribute
  Marks pure LINQ methods to enable InstantHandle inference for delegate parameters in chains.
• NoEnumerationAttribute
  Indicates an IEnumerable parameter is not enumerated.
• LocalizationRequiredAttribute(bool required = true)
  Marks elements requiring localization.
• CannotApplyEqualityOperatorAttribute
  Indicates ==/!= operators are invalid for the type (except null comparisons).
• UsedImplicitlyAttribute(ImplicitUseKindFlags, ImplicitUseTargetFlags) + MeansImplicitUseAttribute(...)
  Marks symbols used implicitly (e.g., via reflection) to suppress unused warnings. ImplicitUseKindFlags: Access, Assign, InstantiatedWithFixedConstructorSignature, InstantiatedNoFixedConstructorSignature. ImplicitUseTargetFlags: Itself, Members, WithMembers.
• PublicAPIAttribute(string comment = null)
  Marks publicly exposed API that must not be removed. Internally uses [MeansImplicitUse(ImplicitUseTargetFlags.WithMembers)].
• SourceTemplateAttribute + MacroAttribute
  Marks extension methods as source templates for IDE expansion (e.g., forEach snippets).
• PathReferenceAttribute(string basePath = null)
  Indicates a parameter is a file/folder path in a web project.

ASP.NET MVC & Razor-Specific Annotations

• AspMvc*Attribute (e.g., AspMvcActionAttribute, AspMvcAreaAttribute, AspMvcControllerAttribute, AspMvcViewAttribute, AspMvcSuppressViewErrorAttribute, etc.)
  Marks parameters/methods for MVC/Razor view resolution (e.g., action names, areas, controllers, views). Many have optional anonymousProperty constructor.
• AspChildControlTypeAttribute(string tagName, Type controlType)
  Specifies child control types for ASP.NET server controls.
• AspDataFieldAttribute, AspDataFieldsAttribute, AspMethodPropertyAttribute, AspRequiredAttributeAttribute(string attribute), AspTypePropertyAttribute(bool createConstructorReferences)
  ASP.NET-specific metadata for data binding and property resolution.
• Razor*Attribute (e.g., RazorSectionAttribute, RazorImportNamespaceAttribute, RazorInjectionAttribute, RazorDirectiveAttribute, RazorWriteLiteralMethodAttribute, RazorWriteMethodAttribute, RazorHelperCommonAttribute, RazorLayoutAttribute)
  Razor view engine metadata for section resolution, imports, and helper methods.
• XamlItemsControlAttribute + XamlItemBindingOfItemsControlAttribute
  XAML binding context resolution for ItemsControl-derived types.

Utility

• NoReorder
  Prevents IDE member reordering for the marked class.

3. Invariants

• No runtime behavior: All attributes are metadata-only. They have no effect at runtime unless consumed by tooling (e.g., ReSharper, analyzers).
• Attribute targets: Each attribute’s AttributeUsage is strictly defined (e.g., CanBeNullAttribute targets methods, parameters, properties, etc.). Applying to an unsupported target is a compile-time error.
• Nullability semantics: [NotNull] and [CanBeNull] are mutually exclusive for the same element. Tooling expects consistency; mixing them may cause conflicting warnings.
• ContractAnnotation syntax: The contract string must follow the specified FDT (Function Definition Table) syntax. Invalid syntax may cause analyzer errors or ignored annotations.
• StringFormatMethodAttribute: The formatParameterName must match an actual parameter name; otherwise, tooling may produce false warnings.
• AssertionConditionAttribute: Only valid on parameters of methods marked with [AssertionMethod].

4. Dependencies

• No external dependencies: This module is self-contained. It uses only System and System.Runtime.CompilerServices (via attributes like AttributeUsage).
• Consumers: Any project referencing DTS.Common.CPU can use these annotations. They are intended for use in other modules within the DTS.Common.* family (e.g., DTS.Common.CPU itself likely consumes them, though not visible in the provided files).
• Tooling dependency: Full benefit requires ReSharper/Rider or compatible analyzers (e.g., JetBrains.Annotations NuGet package). Without tooling, attributes are inert.

5. Gotchas

• AssemblyInfo.cs is metadata-only: The assembly version (1.0.0.0) and GUID (a68ef337-debf-4265-8dec-8acf01e76ee6) are fixed and should not be changed without coordination.
• Annotations.cs is a copy of JetBrains.Annotations: This is a vendored copy of JetBrains’ annotation definitions (MIT-licensed). Do not modify it unless aligning with upstream changes.
• [Obsolete] on TerminatesProgramAttribute: The TerminatesProgramAttribute is deprecated in favor of [ContractAnnotation("=> halt")]. Using it will trigger an obsolete warning.
• AspMvc* attributes are framework-specific: These only make sense in ASP.NET MVC/Razor contexts. Using them in non-MVC projects may confuse tooling without benefit.
• SourceTemplate/Macro require IDE support: These attributes only function in IDEs that support template expansion (e.g., ReSharper). They are ignored in standard compilation.
• ImplicitUse* flags are subtle: Misusing ImplicitUseKindFlags (e.g., omitting InstantiatedNoFixedConstructorSignature when constructors are used reflectively) may cause false "unused constructor" warnings.
• No runtime validation: Attributes like [NotNull] do not enforce null checks at runtime. Developers must still write defensive code.

None identified beyond what is apparent from the source.