Refactor documentation for clarity and detail

lib/core/tbar/TBar.md

@@ -1,68 +1,112 @@
-# TBar Struct
+# TBar: OHLCV Bar Struct
 
-`TBar` is a lightweight, immutable struct representing a single OHLCV (Open, High, Low, Close, Volume) bar. It is designed for high-performance financial data processing with minimal memory overhead.
+## What It Does
 
-## Key Features
+`TBar` is a lightweight, immutable struct representing a single OHLCV (Open, High, Low, Close, Volume) bar. It serves as the fundamental unit for price data in QuanTAlib, designed to hold market data with minimal memory overhead while providing convenient accessors for common price derivations.
 
-- **Memory Efficient**: Pure data type occupying exactly 48 bytes (1 `long` + 5 `double`s).
-- **Immutable**: Thread-safe by design.
-- **Zero-Copy Conversions**: Efficiently converts to `TValue` for individual price components (Open, High, Low, Close, Volume).
-- **Computed Properties**: Provides on-demand calculation of common price averages (HL2, HLC3, etc.) without storage overhead.
-- **SIMD Compatible**: Layout is optimized for potential vectorization in collection types.
+## Design Philosophy
 
-## Structure Definition
+Financial data processing often involves millions of bars. Storing these as classes would create massive GC pressure and memory fragmentation. `TBar` is designed as a **pure data struct** to ensure:
+
+* **Compactness**: Occupies exactly 48 bytes (1 `long` + 5 `double`s), fitting efficiently in memory.
+* **Immutability**: Thread-safe by default; values cannot change once created.
+* **Zero-Cost Abstractions**: Computed properties (like `HL2`) are calculated on-demand, requiring no extra storage.
+
+## How It Works
+
+`TBar` is a `readonly record struct` that stores:
+
+* **Time**: Timestamp in ticks.
+* **Open, High, Low, Close**: Price components.
+* **Volume**: Traded volume.
+
+It includes implicit conversions to `double` (defaulting to Close price) and `TValue` (Time + Close), allowing it to be used interchangeably with simpler types in many contexts.
+
+## Structure
+
+### Definition
 
 ```csharp
-public readonly struct TBar : IEquatable<TBar>
-{
-    public readonly long Time;    // Unix ticks
-    public readonly double Open;
-    public readonly double High;
-    public readonly double Low;
-    public readonly double Close;
-    public readonly double Volume;
-}
+public readonly record struct TBar(long Time, double Open, double High, double Low, double Close, double Volume);
 ```
 
-## Properties
+### Core Properties
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `Time` | `long` | Timestamp in ticks. |
+| `Time` | `long` | Timestamp in ticks (UTC). |
 | `Open` | `double` | Opening price. |
 | `High` | `double` | Highest price. |
 | `Low` | `double` | Lowest price. |
 | `Close` | `double` | Closing price. |
 | `Volume` | `double` | Traded volume. |
-| `AsDateTime` | `DateTime` | `Time` converted to UTC DateTime. |
 
-### Computed Averages
-These properties are calculated on the fly:
-- `HL2`: (High + Low) / 2
-- `OC2`: (Open + Close) / 2
-- `OHL3`: (Open + High + Low) / 3
-- `HLC3`: (High + Low + Close) / 3
-- `OHLC4`: (Open + High + Low + Close) / 4
-- `HLCC4`: (High + Low + Close + Close) / 4
+### Computed Properties (Zero-Storage)
+
+| Property | Formula | Description |
+|----------|---------|-------------|
+| `HL2` | `(H + L) / 2` | Median Price. |
+| `OC2` | `(O + C) / 2` | Midpoint Price. |
+| `OHL3` | `(O + H + L) / 3` | Typical Price (Variant). |
+| `HLC3` | `(H + L + C) / 3` | Typical Price. |
+| `OHLC4` | `(O + H + L + C) / 4` | Weighted Close. |
+| `HLCC4` | `(H + L + 2C) / 4` | Weighted Close (Variant). |
 
 ### TValue Accessors
-Efficiently access components as `TValue` (Time-Value pair):
-- `O`: (Time, Open)
-- `H`: (Time, High)
-- `L`: (Time, Low)
-- `C`: (Time, Close)
-- `V`: (Time, Volume)
+
+Efficiently extracts components as `TValue` pairs:
+
+* `O`, `H`, `L`, `C`, `V`
 
 ## Usage
 
-### Creating a TBar
+### Creating a Bar
+
 ```csharp
-long now = DateTime.UtcNow.Ticks;
-var bar = new TBar(now, 100.0, 105.0, 95.0, 102.0, 1000.0);
+var bar = new TBar(DateTime.UtcNow, 100, 105, 95, 102, 1000);
 ```
 
 ### Implicit Conversions
+
 ```csharp
-double closePrice = bar;      // Implicitly converts to Close price
-TValue value = bar;           // Implicitly converts to (Time, Close)
-DateTime dt = bar;            // Implicitly converts to DateTime
+TBar bar = ...;
+
+// Treat as double (uses Close price)
+double price = bar; 
+
+// Treat as TValue (Time + Close)
+TValue tv = bar;
+
+// Treat as DateTime
+DateTime dt = bar;
+```
+
+### Using Computed Properties
+
+```csharp
+// Calculate Typical Price on the fly
+double typical = bar.HLC3;
+```
+
+## Performance Profile
+
+* **Memory**: 48 bytes per instance.
+* **Allocation**: 0 bytes (Stack allocated).
+* **Access**: Direct field access (no property overhead).
+
+## Integration
+
+`TBar` is the primary input for:
+
+* **TBarSeries**: A collection of bars.
+* **Indicators**: Some indicators (like ATR) require full `TBar` input rather than just a single value.
+
+## Architecture Notes
+
+* **SkipLocalsInit**: Marked with `[SkipLocalsInit]` for performance in tight loops.
+* **AggressiveInlining**: All computed properties are inlined to ensure they are as fast as writing the formula manually.
+
+## References
+
+* [OHLC Chart](https://en.wikipedia.org/wiki/Open-high-low-close_chart)
+* [C# Record Structs](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/record)