140 lines
7.4 KiB
Markdown
140 lines
7.4 KiB
Markdown
---
|
||
source_files:
|
||
- Common/DTS.Common.SerializationPlus/Control/Event/Module/ReviewableDasSerialNumberAttribute.cs
|
||
- Common/DTS.Common.SerializationPlus/Control/Event/Module/ReviewableAttribute.cs
|
||
- Common/DTS.Common.SerializationPlus/Control/Event/Module/ReviewableSampleRateAttribute.cs
|
||
generated_at: "2026-04-16T03:31:05.140610+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "b7f5fb3360deccec"
|
||
---
|
||
|
||
# Module
|
||
|
||
## Documentation: `ReviewableDasSerialNumberAttribute` and Related Classes
|
||
|
||
---
|
||
|
||
### 1. **Purpose**
|
||
|
||
This module provides concrete implementations of `ReviewableAttribute` for capturing and exposing read-only metadata about a `DTS.Slice.Control.Event.Module` instance—specifically, attributes that are relevant during event review or audit workflows. These attributes (e.g., DAS serial number, sample rate, hardware anti-aliasing filter rate, test description) are lazily evaluated via delegates and formatted for display in UI or reporting contexts. The classes exist to support structured, consistent, and type-safe access to module-level configuration and identity data during review processes.
|
||
|
||
---
|
||
|
||
### 2. **Public Interface**
|
||
|
||
All classes are `public` nested within `DTS.Slice.Control.Event.Module`.
|
||
|
||
#### `ReviewableDasSerialNumberAttribute`
|
||
- **Signature**:
|
||
```csharp
|
||
public class ReviewableDasSerialNumberAttribute : ReviewableAttribute
|
||
```
|
||
- **Constructor**:
|
||
```csharp
|
||
public ReviewableDasSerialNumberAttribute(Event.Module module)
|
||
```
|
||
- **Behavior**:
|
||
Initializes a reviewable attribute named `"DAS Serial Number"` whose value is lazily retrieved from `module.DasSerialNumber`. Uses the base class’s `DetermineValueString` delegate mechanism.
|
||
|
||
#### `ReviewableSampleRateAttribute`
|
||
- **Signature**:
|
||
```csharp
|
||
public class ReviewableSampleRateAttribute : ReviewableAttribute
|
||
```
|
||
- **Constructor**:
|
||
```csharp
|
||
public ReviewableSampleRateAttribute(Event.Module module)
|
||
```
|
||
- **Behavior**:
|
||
Initializes a reviewable attribute named `"Sample Rate"`. Value is `module.SampleRateHz.ToString("N")` (numeric formatting with thousand separators, no decimal places implied by `"N"` default).
|
||
|
||
#### `ReviewableTestDescriptionAttribute`
|
||
- **Signature**:
|
||
```csharp
|
||
public class ReviewableTestDescriptionAttribute : ReviewableAttribute
|
||
```
|
||
- **Constructor**:
|
||
```csharp
|
||
public ReviewableTestDescriptionAttribute(Event.Module module)
|
||
```
|
||
- **Behavior**:
|
||
Initializes a reviewable attribute named `"Test Description"`. Value is `module.ParentEvent.Description`. *Note: This accesses the parent `Event`, not the `Module` directly.*
|
||
|
||
#### `ReviewableHardwareFrequencyAttribute`
|
||
- **Signature**:
|
||
```csharp
|
||
public class ReviewableHardwareFrequencyAttribute : ReviewableAttribute
|
||
```
|
||
- **Constructor**:
|
||
```csharp
|
||
public ReviewableHardwareFilterAttribute(Event.Module module)
|
||
```
|
||
- **Behavior**:
|
||
Initializes a reviewable attribute named `"HW AAF"` (Hardware Anti-Alias Filter). Value is `module.AaFilterRateHz.ToString("N2")` (2 decimal places).
|
||
|
||
---
|
||
|
||
### 3. **Invariants**
|
||
|
||
- **All attributes are immutable after construction**: The `name` and `DetermineValueString` delegate are set in the base constructor and never modified.
|
||
- **Value evaluation is deferred**: The delegate passed to `base(...)` is invoked only when the attribute’s value is requested (e.g., for display), not at construction time.
|
||
- **`ReviewableAttribute` base constructor enforces non-null `name` and `calculateValue`**: The protected constructor expects both parameters; the public constructor in subclasses always supplies them.
|
||
- **`ReviewableDasSerialNumberAttribute` and other subclasses must be instantiated with a non-null `Event.Module`**: Otherwise, accessing `module.DasSerialNumber`, `module.SampleRateHz`, etc., will throw a `NullReferenceException`.
|
||
- **`ReviewableAttribute` has two constructors, but only one is usable**:
|
||
- The single-parameter constructor (`ReviewableAttribute(Event.Module)`) is *intentionally non-functional* and throws `NotImplementedException` via a wrapper `Exception`.
|
||
- Only the two-parameter protected constructor (`ReviewableAttribute(string, DetermineValueString)`) is used in practice.
|
||
|
||
---
|
||
|
||
### 4. **Dependencies**
|
||
|
||
#### Dependencies *of* this module:
|
||
- `DTS.Slice.Control.Event.Module` — Required for `module.DasSerialNumber`, `module.SampleRateHz`, `module.AaFilterRateHz`, and `module.ParentEvent`.
|
||
- `DTS.Slice.Control.ReviewableAttribute` — Base class for `ReviewableAttribute`. (Implied by inheritance; source not provided, but referenced in `ReviewableAttribute.cs`.)
|
||
- `DTS.Utilities` — Used for formatting (e.g., `.ToString("N")`), though standard .NET formatting would suffice.
|
||
|
||
#### Dependencies *on* this module:
|
||
- Any code that needs to expose module metadata for review (e.g., UI forms, audit logging, export tools) will instantiate these classes and pass them to a review framework built around `ReviewableAttribute`.
|
||
|
||
#### Inferred relationships:
|
||
- `Event.Module` must define the following properties (not visible in source, but required):
|
||
- `string DasSerialNumber`
|
||
- `double SampleRateHz`
|
||
- `double AaFilterRateHz`
|
||
- `Event ParentEvent` (with `string Description`)
|
||
- `ReviewableAttribute` inherits from `Slice.Control.ReviewableAttribute`, which must define:
|
||
- Constructor: `ReviewableAttribute(string name, DetermineValueString calculateValue)`
|
||
- Property/method to retrieve the formatted value string (via `DetermineValueString` delegate).
|
||
|
||
---
|
||
|
||
### 5. **Gotchas**
|
||
|
||
- **Misleading XML comment for `ReviewableSampleRateAttribute` and `ReviewableHardwareFrequencyAttribute`**:
|
||
Both are documented as “A reviewable filter frequency attribute attached to a specific channel.” — but they are attached to a `Module`, not a `Channel`. (The `ReviewableDasSerialNumberAttribute` comment is similarly inaccurate.)
|
||
|
||
- **`ReviewableTestDescriptionAttribute` accesses `module.ParentEvent.Description`**:
|
||
This implies a parent-child relationship (`Module` → `Event`). If `module.ParentEvent` is `null`, this will throw `NullReferenceException`.
|
||
|
||
- **`ReviewableAttribute` constructor design is fragile**:
|
||
The single-parameter constructor exists solely to fail at runtime. This is a code smell—ideally, it would be `private` or removed entirely.
|
||
|
||
- **String formatting is hardcoded**:
|
||
`"N"` and `"N2"` are used directly in delegates. Changing formatting (e.g., locale, precision) requires source modification.
|
||
|
||
- **No null-safety in value delegates**:
|
||
None of the delegates check for null (e.g., `module.DasSerialNumber` could be `null`, but `ToString()` is called unconditionally). This may yield `"False"` or `""` depending on type, or throw if `DasSerialNumber` is a non-nullable value type.
|
||
|
||
- **Typo in `ReviewableHardwareFrequencyAttribute` constructor name in source**:
|
||
The XML comment says `channel`, but the parameter is named `module`. This is minor but inconsistent.
|
||
|
||
- **No documentation for `DetermineValueString` delegate type**:
|
||
Its signature and contract are unknown from source alone. Assumed to be `Func<string>` or similar.
|
||
|
||
- **No tests or usage examples provided**:
|
||
Behavior is inferred solely from constructor and inheritance. Actual runtime behavior (e.g., how values are consumed) is not verifiable from source.
|
||
|
||
---
|
||
|
||
*Note: All inferences assume standard .NET conventions and the structural clues in the provided source. Behavior of `DetermineValueString` and the parent `ReviewableAttribute` class cannot be fully confirmed without their source.* |