240 lines
No EOL
7 KiB
Markdown
240 lines
No EOL
7 KiB
Markdown
# Documentation vs Source Code Gap Analysis
|
|
|
|
> Generated analysis comparing `botserver/src/` with `botserver/docs/`
|
|
|
|
## Summary
|
|
|
|
| Category | Documented | Implemented | Gap |
|
|
|----------|------------|-------------|-----|
|
|
| BASIC Keywords | ~65 | ~80+ | ~15 undocumented |
|
|
| Source Modules | 18 | 24 | 6 undocumented |
|
|
| Suite Apps | 14 | 14 | ✅ Complete |
|
|
| REST APIs | 22 | 22 | ✅ Complete |
|
|
|
|
---
|
|
|
|
## 1. Undocumented BASIC Keywords
|
|
|
|
The following keywords exist in `src/basic/keywords/` but lack dedicated documentation pages:
|
|
|
|
### High Priority (Commonly Used)
|
|
|
|
| Keyword | Source File | Description |
|
|
|---------|-------------|-------------|
|
|
| `QR CODE` | `qrcode.rs` | Generates QR code images from data |
|
|
| `SEND SMS` | `sms.rs` | Sends SMS messages via Twilio/AWS SNS/Vonage |
|
|
| `PLAY` | `play.rs` | Opens content projector for videos, images, docs |
|
|
| `REMEMBER` | `remember.rs` | Stores user memories with expiration |
|
|
| `BOOK` | `book.rs` | Schedules calendar meetings/appointments |
|
|
| `WEATHER` | `weather.rs` | Gets weather data (API documented, keyword not) |
|
|
|
|
### Medium Priority (Advanced Features)
|
|
|
|
| Keyword | Source File | Description |
|
|
|---------|-------------|-------------|
|
|
| `A2A` | `a2a_protocol.rs` | Agent-to-Agent communication protocol |
|
|
| `ADD BOT` | `add_bot.rs` | Dynamically adds bots to session |
|
|
| `ADD MEMBER` | `add_member.rs` | Adds members to groups/teams |
|
|
| `ADD SUGGESTION` | `add_suggestion.rs` | Adds response suggestions |
|
|
| `HUMAN APPROVAL` | `human_approval.rs` | Human-in-the-loop workflow |
|
|
| `MODEL ROUTE` | `model_routing.rs` | Routes requests to different LLM models |
|
|
| `SEND TEMPLATE` | `send_template.rs` | Sends WhatsApp/channel templates |
|
|
| `SET USER` | `set_user.rs` | Sets current user context |
|
|
|
|
### Low Priority (Internal/Advanced)
|
|
|
|
| Keyword | Source File | Description |
|
|
|---------|-------------|-------------|
|
|
| `EPISODIC MEMORY` | `episodic_memory.rs` | Long-term episodic memory storage |
|
|
| `KNOWLEDGE GRAPH` | `knowledge_graph.rs` | Knowledge graph operations |
|
|
| `LLM` | `llm_keyword.rs` | Direct LLM invocation |
|
|
| `MULTIMODAL` | `multimodal.rs` | Image/audio processing |
|
|
| `PROCEDURE` | `procedures.rs` | BASIC procedure definitions |
|
|
| `ON FORM SUBMIT` | `on_form_submit.rs` | Form submission handlers |
|
|
| `IMPORT/EXPORT` | `import_export.rs` | Data import/export operations |
|
|
|
|
---
|
|
|
|
## 2. Undocumented Source Modules
|
|
|
|
### Modules Without Dedicated Documentation
|
|
|
|
| Module | Path | Purpose | Priority |
|
|
|--------|------|---------|----------|
|
|
| `attendance` | `src/attendance/` | Queue management for human attendants | Medium |
|
|
| `timeseries` | `src/timeseries/` | InfluxDB 3 integration for metrics | Medium |
|
|
| `weba` | `src/weba/` | Placeholder for web app features | Low |
|
|
| `nvidia` | `src/nvidia/` | GPU acceleration (partially documented) | Low |
|
|
| `multimodal` | `src/multimodal/` | Image/video processing | Medium |
|
|
| `console` | `src/console/` | Admin console backend | Low |
|
|
|
|
### Modules With Partial Documentation
|
|
|
|
| Module | Missing Docs |
|
|
|--------|--------------|
|
|
| `llm` | LLM keyword syntax, model routing details |
|
|
| `calendar` | CalDAV integration details, recurrence rules |
|
|
| `meet` | WebRTC/LiveKit integration details |
|
|
|
|
---
|
|
|
|
## 3. Documentation Accuracy Issues
|
|
|
|
### Incorrect or Outdated References
|
|
|
|
1. **keyword-remember.md** - Referenced but file doesn't exist in SUMMARY.md
|
|
2. **keyword-book.md** - Referenced in keyword-create-task.md but no file exists
|
|
3. **keyword-weather.md** - API documented but keyword syntax not documented
|
|
|
|
### Missing from SUMMARY.md
|
|
|
|
These keyword files exist but aren't linked in SUMMARY.md:
|
|
|
|
- `keyword-synchronize.md`
|
|
- `keyword-reference-complete.md`
|
|
- Several template files
|
|
|
|
---
|
|
|
|
## 4. API Endpoint Gaps
|
|
|
|
### Suite App Backend APIs (Recently Implemented)
|
|
|
|
| App | Endpoints | Status |
|
|
|-----|-----------|--------|
|
|
| Analytics | 12 endpoints | ✅ Implemented |
|
|
| Paper | 20+ endpoints | ✅ Implemented |
|
|
| Research | 8 endpoints | ✅ Implemented |
|
|
| Sources | 7 endpoints | ✅ Implemented |
|
|
| Designer | 5 endpoints | ✅ Implemented |
|
|
|
|
### Undocumented Internal APIs
|
|
|
|
| API | Path | Purpose |
|
|
|-----|------|---------|
|
|
| Queue API | `/api/queue/*` | Human attendant queue management |
|
|
| TimeSeries API | N/A | Metrics ingestion (internal only) |
|
|
|
|
---
|
|
|
|
## 5. Recommended Documentation Additions
|
|
|
|
### Immediate Priority
|
|
|
|
1. **Create `keyword-qrcode.md`**
|
|
```basic
|
|
' Generate QR code
|
|
path = QR CODE "https://example.com"
|
|
SEND FILE path
|
|
|
|
' With custom size
|
|
path = QR CODE "data", 512
|
|
```
|
|
|
|
2. **Create `keyword-sms.md`**
|
|
```basic
|
|
' Send SMS
|
|
SEND SMS "+1234567890", "Hello!"
|
|
|
|
' With provider
|
|
SEND SMS phone, message, "twilio"
|
|
```
|
|
|
|
3. **Create `keyword-play.md`**
|
|
```basic
|
|
' Play video
|
|
PLAY "video.mp4"
|
|
|
|
' With options
|
|
PLAY "presentation.pptx" WITH OPTIONS "fullscreen"
|
|
```
|
|
|
|
4. **Create `keyword-remember.md`**
|
|
```basic
|
|
' Remember with expiration
|
|
REMEMBER "user_preference", "dark_mode", "30 days"
|
|
|
|
' Recall later
|
|
pref = RECALL "user_preference"
|
|
```
|
|
|
|
5. **Create `keyword-book.md`**
|
|
```basic
|
|
' Book a meeting
|
|
BOOK "Team Standup" WITH user1, user2 AT "2025-01-20 10:00" FOR 30
|
|
```
|
|
|
|
### Medium Priority
|
|
|
|
1. **Document TimeSeries module** - Add to appendix or chapter-11
|
|
2. **Document Attendance/Queue system** - Add to chapter-10 APIs
|
|
3. **Expand Multimodal docs** - Add keyword reference
|
|
4. **Create A2A Protocol guide** - Multi-agent communication
|
|
|
|
### Low Priority
|
|
|
|
1. Add advanced LLM routing documentation
|
|
2. Document internal console APIs
|
|
3. Add GPU acceleration tuning guide
|
|
|
|
---
|
|
|
|
## 6. Consistency Issues
|
|
|
|
### Naming Conventions
|
|
|
|
| Issue | Location | Fix |
|
|
|-------|----------|-----|
|
|
| `keyword-for-each.md` vs `for_next.rs` | Inconsistent naming | Document both FOR EACH and FOR/NEXT |
|
|
| `keyword-delete-http.md` vs `DELETE` | Overlap | Clarify HTTP DELETE vs data DELETE |
|
|
|
|
### Missing Cross-References
|
|
|
|
- Paper app docs don't reference .gbusers storage (FIXED)
|
|
- Calendar docs don't reference BOOK keyword
|
|
- Meet docs don't reference video/audio keywords
|
|
|
|
---
|
|
|
|
## 7. Action Items
|
|
|
|
### High Priority
|
|
- [ ] Create 5 missing keyword docs (QR CODE, SMS, PLAY, REMEMBER, BOOK)
|
|
- [ ] Add WEATHER keyword syntax to weather.md
|
|
- [ ] Fix broken references in existing docs
|
|
|
|
### Medium Priority
|
|
- [ ] Document attendance/queue module
|
|
- [ ] Add timeseries module to appendix
|
|
- [ ] Create A2A protocol guide
|
|
- [ ] Add multimodal keyword reference
|
|
|
|
### Low Priority
|
|
- [ ] Document internal console APIs
|
|
- [ ] Add advanced configuration examples
|
|
- [ ] Create video tutorials references
|
|
|
|
---
|
|
|
|
## 8. Verification Commands
|
|
|
|
```bash
|
|
# List all keyword files in src
|
|
ls botserver/src/basic/keywords/*.rs | wc -l
|
|
|
|
# List all keyword docs
|
|
ls botserver/docs/src/chapter-06-gbdialog/keyword-*.md | wc -l
|
|
|
|
# Find references to undocumented keywords
|
|
grep -r "QRCODE\|QR CODE\|SEND SMS\|PLAY\|REMEMBER\|BOOK" botserver/docs/
|
|
|
|
# Check for broken links in SUMMARY.md
|
|
grep -oP '\./[^)]+\.md' botserver/docs/src/SUMMARY.md | while read f; do
|
|
[ ! -f "botserver/docs/src/$f" ] && echo "Missing: $f"
|
|
done
|
|
```
|
|
|
|
---
|
|
|
|
*Last updated: 2025-01-20*
|
|
*Analyzed modules: 24 source directories, 100+ documentation files* |