init

enriched-partialglm/Common/DTS.CommonCore/Properties.md

@@ -0,0 +1,80 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Properties/AssemblyInfo.cs
+  - Common/DTS.CommonCore/Properties/Settings.Designer.cs
+  - Common/DTS.CommonCore/Properties/Annotations.cs
+generated_at: "2026-04-16T12:03:42.508191+00:00"
+model: "zai-org/GLM-5-FP8"
+schema_version: 1
+sha256: "e93e9dbcf99f35a2"
+---
+
+# Documentation: DTS.CommonCore Properties
+
+## 1. Purpose
+This module provides assembly-level metadata, application configuration management, and static analysis annotations for the `DTS.CommonCore` library. It defines the assembly identity (version 1.0.0.0, title "Common"), exposes a strongly-typed settings accessor for file paths (specifically `TilesLocation`), and embeds a comprehensive suite of JetBrains ReSharper annotations within the `DTS.Common.Annotations` namespace to support nullability checks, method contracts, and MVC/Razor inspections during development.
+
+## 2. Public Interface
+
+### Class: `DTS.Common.Properties.Settings`
+Defined in `Settings.Designer.cs`. This is an internal, sealed class inheriting from `System.Configuration.ApplicationSettingsBase`.
+
+*   **`static Settings Default { get; }`**
+    *   Returns the singleton instance of the settings class, synchronized for thread safety.
+*   **`string TilesLocation { get; }`**
+    *   An application-scoped setting representing a directory path.
+    *   Default Value: `"Assets\\Tiles\\"`
+
+### Namespace: `DTS.Common.Annotations`
+Defined in `Annotations.cs`. Contains attributes used for static code analysis. Key classes include:
+
+**Nullability & State:**
+*   `CanBeNullAttribute`: Indicates an element value can be null.
+*   `NotNullAttribute`: Indicates an element value can never be null.
+*   `ItemNotNullAttribute`: Indicates collection items/Task results are not null.
+*   `ItemCanBeNullAttribute`: Indicates collection items/Task results can be null.
+*   `PureAttribute`: Indicates a method has no observable side effects.
+
+**Contracts & Logic:**
+*   `ContractAnnotationAttribute`: Describes input/output dependencies (e.g., `"null => null"`).
+*   `AssertionMethodAttribute`: Marks a method as an assertion that halts flow.
+*   `AssertionConditionAttribute`: Marks a parameter as the condition for an assertion.
+*   `TerminatesProgramAttribute`: (Obsolete) Indicates method termination.
+
+**Usage & Visibility:**
+*   `UsedImplicitlyAttribute`: Suppresses "unused" warnings for symbols accessed via reflection.
+*   `MeansImplicitUseAttribute`: Applied to attributes to suppress "unused" warnings on targets.
+*   `PublicAPIAttribute`: Marks API as publicly available and treated as used.
+*   `InstantHandleAttribute`: Indicates a parameter (delegate/enumerable) is fully handled during the method execution.
+
+**MVC & Razor Specifics:**
+*   `AspMvcActionAttribute`, `AspMvcControllerAttribute`, `AspMvcViewAttribute`: Hints for MVC routing parameters.
+*   `RazorSectionAttribute`, `RazorImportNamespaceAttribute`: Hints for Razor syntax.
+
+**Templates:**
+*   `SourceTemplateAttribute`: Marks an extension method as a source template for code completion.
+*   `MacroAttribute`: Defines macros for source template parameters.
+
+### Assembly Metadata (`AssemblyInfo.cs`)
+*   **Title:** "Common"
+*   **Version:** "1.0.0.0"
+*   **GUID:** `d16201c7-478c-4b92-ba6e-a0d39fd5f081`
+*   **ComVisible:** `false`
+
+## 3. Invariants
+*   **Thread Safety:** The `Settings.Default` property is guaranteed to be thread-safe due to the `Synchronized` wrapper used in its initialization.
+*   **Scope:** The `Settings` class is defined as `internal sealed`, restricting access to within the `DTS.CommonCore` assembly.
+*   **Read-Only Settings:** The `TilesLocation` property is application-scoped (`ApplicationScopedSettingAttribute`), meaning it is read-only at runtime and cannot be modified by user code.
+*   **Analysis Only:** Attributes defined in `Annotations.cs` do not affect runtime behavior; they are strictly for static analysis tools (specifically ReSharper/Rider).
+
+## 4. Dependencies
+*   **System.Configuration:** Required by `Settings.Designer.cs` for `ApplicationSettingsBase`.
+*   **System.Reflection:** Required by `AssemblyInfo.cs` for assembly attributes.
+*   **System.Runtime.CompilerServices:** Required for `CompilerGeneratedAttribute` and `InternalsVisibleTo` logic.
+*   **System.Runtime.InteropServices:** Required for `ComVisible` and `Guid` attributes.
+
+## 5. Gotchas
+*   **Namespace Discrepancy:** The assembly title is "Common", the file path suggests "DTS.CommonCore", but the settings reside in the `DTS.Common.Properties` namespace. The annotations reside in `DTS.Common.Annotations`. Developers should verify the correct namespace when referencing these components.
+*   **Hardcoded Path Separator:** The `TilesLocation` setting uses Windows-style backslashes (`"Assets\\Tiles\\"`). This may cause cross-platform compatibility issues if the application is run on non-Windows systems without path normalization logic elsewhere in the codebase.
+*   **Auto-Generated Code:** `Settings.Designer.cs` contains a header warning that manual changes will be lost if the code is regenerated. Settings should be managed via the Visual Studio settings designer or the `app.config` file.
+*   **Company Metadata:** The `AssemblyInfo.cs` lists `AssemblyCompany` as "Microsoft". This appears to be template boilerplate and may not reflect the actual ownership of the proprietary codebase.