116 lines
5.8 KiB
Markdown
116 lines
5.8 KiB
Markdown
---
|
||
source_files:
|
||
- Common/DTS.Common.Serialization/Control/ReviewableAttribute.cs
|
||
- Common/DTS.Common.Serialization/Control/IntervalSec.cs
|
||
generated_at: "2026-04-16T03:39:42.724755+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "b95e2bb79309f305"
|
||
---
|
||
|
||
# Control
|
||
|
||
## Documentation: `DTS.Slice.Control` Namespace – ReviewableAttribute & IntervalSec
|
||
|
||
---
|
||
|
||
### 1. Purpose
|
||
|
||
This module provides foundational types for representing *reviewable* attributes (e.g., displayable metadata in a UI review tab) and *time intervals* (in seconds) within the DTS Slice Control domain. `ReviewableAttribute` serves as an abstract base for dynamically computing and exposing attribute values (e.g., channel status, configuration metadata) for review purposes, while `IntervalSec` encapsulates a time range with begin/end times and supports interoperability with a serialization-specific counterpart via implicit conversions.
|
||
|
||
---
|
||
|
||
### 2. Public Interface
|
||
|
||
#### `ReviewableAttribute` (Abstract Class)
|
||
|
||
- **`ReviewableAttribute(string name, DetermineValueString calculateValue)`**
|
||
Constructor. Initializes the attribute with a name and a delegate used to compute the value on demand. Throws `ReviewableAttribute.Exception` on failure.
|
||
|
||
- **`string Name { get; }`**
|
||
Read-only property returning the attribute’s display name.
|
||
|
||
- **`string Value { get; }`**
|
||
Read-only property that invokes the `CalculateValue` delegate to compute the current value. On exception during computation, logs the error and returns `"N/A"` (does *not* throw).
|
||
|
||
- **`delegate string DetermineValueString();`**
|
||
Public delegate defining the signature for value-computation methods.
|
||
|
||
- **`private DetermineValueString CalculateValue { get; set; }`**
|
||
Private property storing the delegate. Throws `ApplicationException` if accessed before initialization.
|
||
|
||
#### `IntervalSec` (Concrete Class)
|
||
|
||
- **`IntervalSec()`**
|
||
Parameterless constructor. Leaves `Begin` and `End` uninitialized (default to `0.0` due to `Property<double>` initialization, but semantically "uninitialized" per comment).
|
||
|
||
- **`IntervalSec(double begin, double end)`**
|
||
Constructor initializing `Begin` and `End` to specified values. Throws generic `Exception` on failure.
|
||
|
||
- **`double Begin { get; set; }`**
|
||
Read/write property for the interval’s start time (seconds).
|
||
|
||
- **`double End { get; set; }`**
|
||
Read/write property for the interval’s end time (seconds).
|
||
|
||
- **`public static implicit operator Serialization.Test.IntervalSec(IntervalSec thisInterval)`**
|
||
Implicit conversion to `DTS.Serialization.Test.IntervalSec`, using current `Begin`/`End`.
|
||
|
||
- **`public static implicit operator IntervalSec(Serialization.Test.IntervalSec thatInterval)`**
|
||
Implicit conversion *from* `DTS.Serialization.Test.IntervalSec`, constructing a new instance.
|
||
|
||
- **`public override bool Equals(object obj)`**
|
||
Memberwise equality check against another `IntervalSec`. Returns `false` if `obj` is `null` or not `IntervalSec`.
|
||
|
||
- **`public override int GetHashCode()`**
|
||
Returns base hash code (note: does *not* combine `Begin`/`End` explicitly—see *Gotchas*).
|
||
|
||
---
|
||
|
||
### 3. Invariants
|
||
|
||
- **`ReviewableAttribute`**
|
||
- `Name` must be non-null (enforced by `Property<string>` constructor with `null` as default, but no explicit validation—*potential risk*).
|
||
- `CalculateValue` must be assigned before `Value` is accessed; otherwise, `ApplicationException` is thrown.
|
||
- `Value` computation *never* throws; exceptions are caught and logged, returning `"N/A"`.
|
||
|
||
- **`IntervalSec`**
|
||
- No invariant enforces `Begin ≤ End`; invalid intervals (e.g., `Begin > End`) are permitted.
|
||
- `Begin` and `End` default to `0.0` (via `Property<double>` initialization), but the parameterless constructor comment states they are "uninitialized"—this is a semantic mismatch.
|
||
|
||
---
|
||
|
||
### 4. Dependencies
|
||
|
||
- **`DTS.Slice.Control.ReviewableAttribute`**
|
||
- *Depends on*:
|
||
- `DTS.Utilities` (for `APILogger`, `Exceptional`, `Property<T>`)
|
||
- `DTS.Utilities.DotNetProgrammingConstructs` (for `Property<T>`)
|
||
- *Used by*: Unknown from source—likely subclassed by domain-specific reviewable attributes (e.g., `ChannelAttribute`, `SystemStatusAttribute`).
|
||
|
||
- **`DTS.Slice.Control.IntervalSec`**
|
||
- *Depends on*:
|
||
- `DTS.Common.Utilities`
|
||
- `DTS.Common.Utilities.DotNetProgrammingConstructs` (for `Property<double>`, `Exceptional`)
|
||
- `DTS.Serialization.Test.IntervalSec` (for implicit conversions)
|
||
- *Used by*: Likely in time-windowing or data-slicing logic (e.g., selecting data within a time range).
|
||
|
||
---
|
||
|
||
### 5. Gotchas
|
||
|
||
- **`ReviewableAttribute`**
|
||
- `CalculateValue` is a *private* property—subclasses cannot override or inspect it directly. Initialization must occur in the base constructor.
|
||
- `Value` silently fails on computation error (`"N/A"`), which may mask bugs if not logged.
|
||
- No validation on `name` parameter (e.g., null/empty); `Property<string>` allows `null`.
|
||
|
||
- **`IntervalSec`**
|
||
- `GetHashCode()` does *not* incorporate `Begin`/`End`, violating the contract that equal objects must have equal hash codes. This will cause failures in hash-based collections (e.g., `HashSet`, `Dictionary`).
|
||
- `Begin`/`End` default to `0.0` despite constructor comment implying "uninitialized" state—this may lead to false positives (e.g., interval `[0.0, 0.0]` treated as valid).
|
||
- Implicit conversions assume `Serialization.Test.IntervalSec` has matching `Begin`/`End` properties; no validation on conversion.
|
||
|
||
- **Both**
|
||
- Heavy use of `try`/`catch` blocks wrapping property accessors and constructors—suggests legacy error-handling pattern. Consider refactoring to reduce overhead.
|
||
- Reliance on `Property<T>` wrapper (not shown) implies a custom property system; behavior (e.g., change notifications) is not documented here.
|
||
|
||
None identified beyond the above. |