Skip to content

Commit 057aa8e

Browse files
committed
Fix documentation accuracy across 74 files
Comprehensive audit of all HORUS documentation against actual codebase. Key fixes: corrected API method names, removed nonexistent builder methods, fixed Python hardware node constructor signatures, removed false AVX512 claims, corrected SIMD thresholds, added planned-feature notices for unimplemented APIs, fixed metrics field names, and removed deleted message type pages.
1 parent bb49172 commit 057aa8e

74 files changed

Lines changed: 1435 additions & 3562 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

MDX_GUIDELINES.md

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -26,15 +26,15 @@
2626

2727
**WRONG**:
2828
```markdown
29-
### Error: "Failed to create Hub<T>"
29+
### Error: "Failed to create Topic<T>"
3030
```
3131

3232
**CORRECT**:
3333
```markdown
34-
### Error: "Failed to create `Hub<T>`"
34+
### Error: "Failed to create `Topic<T>`"
3535
```
3636

37-
**Why**: MDX interprets `Hub<T>` as a JSX component. Always wrap generic types in backticks.
37+
**Why**: MDX interprets `Topic<T>` as a JSX component. Always wrap generic types in backticks.
3838

3939
### 3. Comparison Operators in Text
4040

@@ -89,7 +89,7 @@ Inside code blocks, you can use `<` and `>` normally:
8989

9090
```markdown
9191
\`\`\`rust
92-
let hub: Hub<f32> = Hub::new("topic")?;
92+
let topic: Topic<f32> = Topic::new("sensor")?;
9393
if value < 100 {
9494
// This is fine inside code blocks
9595
}
@@ -101,7 +101,7 @@ if value < 100 {
101101
Inside backticks, you can use `<` and `>`:
102102

103103
```markdown
104-
Use `Hub<T>` for pub-sub messaging.
104+
Use `Topic<T>` for IPC messaging.
105105
Values `<100` are considered low.
106106
```
107107

@@ -117,7 +117,7 @@ Values `<100` are considered low.
117117
## Quick Checklist Before Committing
118118

119119
- [ ] Search file for `<[0-9]` patterns outside code blocks
120-
- [ ] Search file for `<[A-Z]` patterns (like `Hub<T>`) outside backticks
120+
- [ ] Search file for `<[A-Z]` patterns (like `Topic<T>`) outside backticks
121121
- [ ] Check that all comparison operators use HTML entities
122122
- [ ] Verify headings don't start with raw numbers
123123
- [ ] Build locally: `npm run build` should show no MDX errors
@@ -141,8 +141,8 @@ If you see "Error loading doc" messages, you likely have an MDX syntax issue.
141141
**Fix**: Change to `&lt;1`
142142

143143
### "Unexpected character before name, expected a letter"
144-
**Cause**: Using generic types without backticks (e.g., `Hub<T>`)
145-
**Fix**: Wrap in backticks: `` `Hub<T>` ``
144+
**Cause**: Using generic types without backticks (e.g., `Topic<T>`)
145+
**Fix**: Wrap in backticks: `` `Topic<T>` ``
146146

147147
## Files to Check
148148

README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ We welcome contributions! To contribute to the documentation:
107107

108108
Common mistakes to avoid:
109109
- Using `<` directly in text (e.g., `<1%` should be `&lt;1%`)
110-
- Writing generic types without backticks (e.g., `Hub<T>` should be `` `Hub<T>` ``)
110+
- Writing generic types without backticks (e.g., `Topic<T>` should be `` `Topic<T>` ``)
111111
- Starting headings with numbers
112112

113113
General guidelines:

components/DocsSidebar.tsx

Lines changed: 6 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,7 @@ const sections: SidebarSection[] = [
6565
{ title: "Message Types", href: "/concepts/message-types", order: 7 },
6666
{ title: "Real-Time Nodes", href: "/concepts/realtime-nodes", order: 9 },
6767
{ title: "HFrame Transforms", href: "/concepts/hframe", order: 10 },
68+
{ title: "Zero-Overhead IPC", href: "/concepts/zero-overhead-ipc", order: 11 },
6869
{ title: "Multi-Language", href: "/concepts/multi-language", order: 13 },
6970
],
7071
},
@@ -90,17 +91,15 @@ const sections: SidebarSection[] = [
9091
children: [
9192
{ title: "Overview", href: "/rust/api/messages", order: 0 },
9293
{ title: "Control", href: "/rust/api/control-messages", order: 1 },
93-
{ title: "Coordination", href: "/rust/api/coordination-messages", order: 2 },
94-
{ title: "Diagnostics", href: "/rust/api/diagnostics-messages", order: 3 },
94+
{ title: "Diagnostics", href: "/rust/api/diagnostics-messages", order: 2 },
9595
{ title: "Force", href: "/rust/api/force-messages", order: 4 },
9696
{ title: "Geometry", href: "/rust/api/geometry-messages", order: 5 },
9797

9898
{ title: "ML", href: "/rust/api/ml-messages", order: 7 },
9999
{ title: "Navigation", href: "/rust/api/navigation-messages", order: 8 },
100100
{ title: "Perception", href: "/rust/api/perception-messages", order: 9 },
101101
{ title: "Sensor", href: "/rust/api/sensor-messages", order: 10 },
102-
{ title: "Timing", href: "/rust/api/timing-messages", order: 11 },
103-
{ title: "Vision", href: "/rust/api/vision-messages", order: 12 },
102+
{ title: "Vision", href: "/rust/api/vision-messages", order: 10 },
104103
]
105104
},
106105
]
@@ -173,12 +172,9 @@ const sections: SidebarSection[] = [
173172
{ title: "BlackBox Recorder", href: "/advanced/blackbox", order: 7 },
174173
{ title: "Circuit Breaker", href: "/advanced/circuit-breaker", order: 9 },
175174
{ title: "Safety Monitor", href: "/advanced/safety-monitor", order: 10 },
176-
{ title: "Checkpoint System", href: "/advanced/checkpoint", order: 11 },
177-
{ title: "Model Registry", href: "/advanced/model-registry", order: 12 },
178-
{ title: "Record & Replay", href: "/advanced/record-replay", order: 13 },
179-
{ title: "Redundancy", href: "/advanced/redundancy", order: 14 },
180-
{ title: "Telemetry", href: "/advanced/telemetry", order: 15 },
181-
{ title: "Real-Time Configuration", href: "/advanced/rt-config", order: 16 },
175+
{ title: "Model Registry", href: "/advanced/model-registry", order: 11 },
176+
{ title: "Record & Replay", href: "/advanced/record-replay", order: 12 },
177+
{ title: "Real-Time Configuration", href: "/advanced/rt-config", order: 13 },
182178
],
183179
},
184180
{

components/PrevNextNav.tsx

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,6 @@ const allPages: DocLink[] = [
5353
{ title: "Hardware Discovery", href: "/rust/api/hardware" },
5454
{ title: "Messages Overview", href: "/rust/api/messages" },
5555
{ title: "Control Messages", href: "/rust/api/control-messages" },
56-
{ title: "Coordination Messages", href: "/rust/api/coordination-messages" },
5756
{ title: "Diagnostics Messages", href: "/rust/api/diagnostics-messages" },
5857
{ title: "Force Messages", href: "/rust/api/force-messages" },
5958
{ title: "Geometry Messages", href: "/rust/api/geometry-messages" },
@@ -62,7 +61,6 @@ const allPages: DocLink[] = [
6261
{ title: "Navigation Messages", href: "/rust/api/navigation-messages" },
6362
{ title: "Perception Messages", href: "/rust/api/perception-messages" },
6463
{ title: "Sensor Messages", href: "/rust/api/sensor-messages" },
65-
{ title: "Timing Messages", href: "/rust/api/timing-messages" },
6664
{ title: "Vision Messages", href: "/rust/api/vision-messages" },
6765
{ title: "Rust Examples", href: "/rust/examples" },
6866
{ title: "Basic Examples", href: "/rust/examples/basic-examples" },

content/docs/advanced/blackbox.mdx

Lines changed: 15 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -18,17 +18,7 @@ The BlackBox system:
1818

1919
## Enabling BlackBox
2020

21-
### Via Scheduler Builder (Recommended)
22-
23-
```rust
24-
use horus::prelude::*;
25-
26-
// Enable with 16MB buffer
27-
let scheduler = Scheduler::new()
28-
.with_blackbox(16); // 16MB flight recorder
29-
```
30-
31-
### Via Deploy Preset
21+
### Via Deploy Preset (Recommended)
3222

3323
The `deploy()` preset enables blackbox automatically with 16MB:
3424

@@ -44,13 +34,7 @@ let scheduler = Scheduler::deploy();
4434
```rust
4535
use horus::prelude::*;
4636

47-
// Using the builder method
48-
let config = SchedulerConfig::standard()
49-
.with_black_box(true, 10); // Enabled with 10MB buffer
50-
51-
let scheduler = Scheduler::new().with_config(config);
52-
53-
// Or set fields directly
37+
// Set blackbox fields on SchedulerConfig
5438
let mut config = SchedulerConfig::standard();
5539
config.monitoring.black_box_enabled = true;
5640
config.monitoring.black_box_size_mb = 10;
@@ -137,7 +121,7 @@ blackbox.record(BlackBoxEvent::DeadlineMiss {
137121
### Get All Events
138122

139123
```rust
140-
let events = blackbox.get_events();
124+
let events = blackbox.events();
141125
println!("Total events: {}", events.len());
142126

143127
for record in &events {
@@ -155,7 +139,7 @@ Each `BlackBoxRecord` contains:
155139
Filter for error-related events (errors, deadline misses, WCET violations, circuit breaker changes, emergency stops):
156140

157141
```rust
158-
let anomalies = blackbox.get_anomalies();
142+
let anomalies = blackbox.anomalies();
159143
for record in &anomalies {
160144
println!("[tick {}] {:?}", record.tick, record.event);
161145
}
@@ -178,13 +162,16 @@ The Scheduler provides read and write access to its blackbox:
178162
```rust
179163
use horus::prelude::*;
180164

181-
let mut scheduler = Scheduler::new()
182-
.with_blackbox(16);
165+
let mut config = SchedulerConfig::standard();
166+
config.monitoring.black_box_enabled = true;
167+
config.monitoring.black_box_size_mb = 16;
168+
169+
let mut scheduler = Scheduler::new().with_config(config);
183170

184171
// Read-only access
185172
if let Some(bb) = scheduler.blackbox() {
186-
let events = bb.get_events();
187-
let anomalies = bb.get_anomalies();
173+
let events = bb.events();
174+
let anomalies = bb.anomalies();
188175
println!("Recorded {} events, {} anomalies", events.len(), anomalies.len());
189176
}
190177

@@ -223,7 +210,7 @@ std::thread::spawn(move || {
223210

224211
| Parameter | Default | Description |
225212
|-----------|---------|-------------|
226-
| Buffer size | 0 (disabled) | Set via `BlackBox::new(mb)` or `with_blackbox(mb)` |
213+
| Buffer size | 0 (disabled) | Set via `BlackBox::new(mb)` or `config.monitoring.black_box_size_mb` |
227214
| Records per MB | ~5,000 | Estimated at ~200 bytes per record |
228215
| Max pre-allocated | 100,000 records | Initial capacity cap |
229216
| Min buffer | 1,000 records | Minimum regardless of size |
@@ -245,21 +232,20 @@ After a failure, use the blackbox to investigate what happened:
245232
```rust
246233
use horus::prelude::*;
247234

248-
let mut scheduler = Scheduler::new()
249-
.with_blackbox(16);
235+
let mut scheduler = Scheduler::deploy();
250236

251237
// ... run application ...
252238

253239
// After a failure, inspect the blackbox
254240
if let Some(bb) = scheduler.blackbox() {
255-
let anomalies = bb.get_anomalies();
241+
let anomalies = bb.anomalies();
256242
println!("=== ANOMALIES ({}) ===", anomalies.len());
257243
for record in &anomalies {
258244
println!("[tick {}] {:?}", record.tick, record.event);
259245
}
260246

261247
// Look at all events around the failure
262-
let all_events = bb.get_events();
248+
let all_events = bb.events();
263249
println!("\n=== LAST {} EVENTS ===", all_events.len());
264250
for record in all_events.iter().rev().take(20) {
265251
println!("[tick {}] {:?}", record.tick, record.event);

content/docs/advanced/circuit-breaker.mdx

Lines changed: 3 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -189,17 +189,7 @@ The scheduler automatically manages circuit breakers for nodes:
189189
```rust,ignore
190190
use horus::prelude::*;
191191
192-
// Using builder method
193-
let config = SchedulerConfig::standard()
194-
.with_circuit_breaker(true);
195-
196-
let scheduler = Scheduler::new().with_config(config);
197-
198-
// Or use the convenience alias
199-
let config = SchedulerConfig::deterministic()
200-
.circuit_breaker(); // Same as .with_circuit_breaker(true)
201-
202-
// Or configure thresholds directly
192+
// Configure thresholds directly
203193
let mut config = SchedulerConfig::standard();
204194
config.fault.circuit_breaker_enabled = true;
205195
config.fault.max_failures = 5;
@@ -208,8 +198,8 @@ config.fault.circuit_timeout_ms = 5000;
208198
209199
let scheduler = Scheduler::new().with_config(config);
210200
211-
// Circuit breaker events are recorded to BlackBox
212-
// CircuitBreakerChange { name, new_state, failure_count }
201+
// Note: standard() preset already has circuit_breaker_enabled = true
202+
// safety_critical() and deterministic() presets have it disabled
213203
```
214204

215205
## Per-Node Configuration

0 commit comments

Comments
 (0)