docs: Comprehensive examples and API documentation improvements#39
Conversation
IMPROVEMENTS: 1. New Example: multi_flight_export.rs - Demonstrates how to export ALL flights from a BBL file - Shows proper use of parse_bbl_file_all_logs() - Displays flight numbering and automatic suffixing 2. Updated Examples/README.md - Added quick-start section with usage for both single/multi-flight cases - Clear explanation of when to use each example - API pattern guide showing correct usage - Common mistakes section with dos/don'ts - Flight numbering table explaining suffixes 3. Updated csv_export.rs Comments - Added prominent note about multi-log handling - Reference to multi_flight_export example - Clarified that this exports only first flight 4. Enhanced CRATE_USAGE.md - Added warning section about parse_bbl_file() vs parse_bbl_file_all_logs() - Renamed sections for clarity (Single-flight, Multi-flight) - Best practices: Handle both cases with parse_bbl_file_all_logs() - New Flight Numbering section with detailed explanation - Suffix rules documentation - Production code recommendation This addresses the issue where users might accidentally use parse_bbl_file() on multi-flight files and only export the first flight. The new example and documentation make the distinction clear.
Consolidated duplicate content: - Removed brief 3-line description of export_demo (lines 72-77) - Replaced with single cross-reference to the comprehensive section below - Comprehensive section (Features, Usage, Example Output, Implementation Notes) remains intact at line 148+ - Anchor #export_demo-example correctly links from line 73 Improves readability and reduces redundancy while maintaining complete documentation.
Consolidated duplicate documentation: - Removed redundant csv_export block from 'Additional Export Examples' section - Replaced with single cross-reference to comprehensive entry in 'Available Examples' - Anchor links correctly reference sections above - Reduces file length by 11 lines while maintaining complete documentation Improves readability by centralizing example documentation.
Addressed ambiguity about bbl_parser CLI tool usage: Changes: 1. Removed confusing CLI fallback references from gpx_export and event_export - Deleted: 'Use CLI: bbl_parser --gps flight.BBL' - Deleted: 'Use CLI: bbl_parser --event flight.BBL' 2. Added new 'CLI Tool vs Library Examples' section explaining: - What the CLI binary is (src/main.rs in the crate) - When to use CLI (command-line processing, batch operations) - When to use library API (Rust integration, programmatic access) - How to build/install the CLI - Relationship between library, examples, and CLI This clarifies that: - bbl_parser CLI is part of the crate (not separate tool) - It's a convenience wrapper on the library API - Readers should choose based on their use case - Examples focus on library integration patterns
Fixed inaccurate documentation: Test Results (BTFL_KWONGKAN_10inch_0326_00_Filter.BBL): - gpx_export: ✅ Successfully exported 833 GPS coordinates - Includes home position, elevation, timestamps - Valid GPX format with proper structure - event_export: ✅ Successfully exported 5 events - Includes sync beep, flight mode, disarm, log end - Proper timestamp collection Documentation Updates: - gpx_export status: ⏳ Partial → ✅ Fully functional - event_export status: ⏳ Partial → ✅ Fully functional - multi_export status: ⏳ Partial → ✅ Production Ready - export_demo status: ⏳ Partial → ✅ Production Ready - Removed misleading footnote about parser enhancement needed - Updated implementation status table GPS and Event data collection are fully functional in the parser module. No parser enhancements are needed.
- Changed multi_export status from 'Fully functional for CSV, ⏳ GPS/Event pending' to '✅ Fully functional - Exports all available formats' - Aligns with verified GPS and Event export functionality
- Removed unused 'suffix' variable - Simplified conditional output with direct if/else branches - Clearer output messages: - Single flight: '✓ Exported' - Multiple flights: '✓ Exported as .NN.csv' - Reduces code complexity and improves readability
- Added status line after Usage examples (line 171) - Consistent with gpx_export, event_export, and multi_export examples - Status: '✅ Fully functional - Exports all formats (CSV, GPX, events) with comprehensive logging' - Improves visual consistency and clarity across all example sections
📝 WalkthroughWalkthroughThis PR updates documentation to clarify single- vs multi-flight parsing and export behavior, adds extensive guidance on log numbers and per-flight suffixing, renames usage sections, and introduces a new Rust example demonstrating exporting all flights using parse_bbl_file_all_logs and export_to_csv. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~13 minutes Possibly related PRs
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Organization UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🧰 Additional context used🧠 Learnings (7)📓 Common learnings📚 Learning: 2025-12-08T21:15:02.434ZApplied to files:
📚 Learning: 2025-12-19T21:17:26.889ZApplied to files:
📚 Learning: 2025-12-19T21:17:26.889ZApplied to files:
📚 Learning: 2025-12-19T21:17:26.889ZApplied to files:
📚 Learning: 2025-12-19T21:17:26.889ZApplied to files:
📚 Learning: 2025-12-19T21:17:26.889ZApplied to files:
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
🔇 Additional comments (7)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
examples/README.md (1)
42-54: Minor: Add language identifier to fenced code block.The fenced code block showing example output should specify a language identifier for proper syntax highlighting and markdown linting compliance.
Suggested fix
-``` +```text Flight 1/3: Frames: 1,787 ✓ Exported as .01.csvBased on learnings from static analysis hints.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
CRATE_USAGE.mdexamples/README.mdexamples/csv_export.rsexamples/multi_flight_export.rs
🧰 Additional context used
🧠 Learnings (11)
📓 Common learnings
Learnt from: nerdCopter
Repo: nerdCopter/bbl_parser PR: 0
File: :0-0
Timestamp: 2025-12-08T21:15:02.434Z
Learning: Repo nerdCopter/bbl_parser: For outside-diff review notes, prefer a compact, single-block comment with flat bullets (file:line → note), no nested <details> or admonitions; overflow should be linked via gist. Maintainer: nerdCopter.
Learnt from: nerdCopter
Repo: nerdCopter/bbl_parser PR: 0
File: :0-0
Timestamp: 2025-12-08T21:15:02.434Z
Learning: For bbl_parser reviews: nerdCopter prefers compact, single-block “outside diff” comments without nested <details> or admonitions; use flat bullets with file:line references and link a gist for overflow.
Learnt from: CR
Repo: nerdCopter/bbl_parser PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-19T21:17:26.889Z
Learning: Applies to src/lib.rs : Public API must include: `parse_bbl_file()`, `parse_bbl_bytes()`, `BBLLog`, `ExportOptions`, `export_to_csv()`, `export_to_gpx()`, `export_to_event()`, conversion utilities, parser helpers
Learnt from: nerdCopter
Repo: nerdCopter/bbl_parser PR: 2
File: LICENSE_COMMERCIAL:1-4
Timestamp: 2025-08-29T19:52:05.099Z
Learning: nerdCopter prefers to avoid publishing personal information in license files for privacy and security reasons, as they are an individual maintainer rather than a company.
Learnt from: nerdCopter
Repo: nerdCopter/bbl_parser PR: 2
File: README.md:520-521
Timestamp: 2025-08-29T19:53:41.354Z
Learning: nerdCopter uses AGPL-3.0-or-later licensing for the bbl_parser project with a dual-licensing approach that includes a separate commercial license option.
Learnt from: nerdCopter
Repo: nerdCopter/bbl_parser PR: 2
File: CONTRIBUTING.md:9-14
Timestamp: 2025-08-21T20:25:45.741Z
Learning: nerdCopter prefers to keep CLA language general using "project maintainer" rather than specifying a legal entity name, as they are an individual maintainer without an associated company.
Learnt from: nerdCopter
Repo: nerdCopter/bbl_parser PR: 2
File: LICENSE_COMMERCIAL:0-0
Timestamp: 2025-08-29T20:15:04.624Z
Learning: nerdCopter prefers clear positive indicators (✅) when describing fixes rather than using ❌ symbols which can be confusing when describing what was corrected in a positive context.
📚 Learning: 2025-12-19T21:17:26.889Z
Learnt from: CR
Repo: nerdCopter/bbl_parser PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-19T21:17:26.889Z
Learning: Applies to src/lib.rs : Public API must include: `parse_bbl_file()`, `parse_bbl_bytes()`, `BBLLog`, `ExportOptions`, `export_to_csv()`, `export_to_gpx()`, `export_to_event()`, conversion utilities, parser helpers
Applied to files:
examples/csv_export.rsexamples/multi_flight_export.rsCRATE_USAGE.mdexamples/README.md
📚 Learning: 2025-12-19T21:17:26.889Z
Learnt from: CR
Repo: nerdCopter/bbl_parser PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-19T21:17:26.889Z
Learning: Applies to src/main.rs : CLI (`src/main.rs`) uses library export functions (`export_to_csv`, `export_to_gpx`, `export_to_event`) with CLI-specific status messages as thin wrapper with zero public functions
Applied to files:
examples/csv_export.rsexamples/multi_flight_export.rsCRATE_USAGE.mdexamples/README.md
📚 Learning: 2025-12-08T21:15:02.434Z
Learnt from: nerdCopter
Repo: nerdCopter/bbl_parser PR: 0
File: :0-0
Timestamp: 2025-12-08T21:15:02.434Z
Learning: Repo nerdCopter/bbl_parser: For outside-diff review notes, prefer a compact, single-block comment with flat bullets (file:line → note), no nested <details> or admonitions; overflow should be linked via gist. Maintainer: nerdCopter.
Applied to files:
examples/csv_export.rsCRATE_USAGE.md
📚 Learning: 2025-12-19T21:17:26.889Z
Learnt from: CR
Repo: nerdCopter/bbl_parser PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-19T21:17:26.889Z
Learning: Applies to src/export.rs : The CSV output must precisely match the format and header order of blackbox_decode CSV files
Applied to files:
examples/csv_export.rsexamples/multi_flight_export.rsCRATE_USAGE.mdexamples/README.md
📚 Learning: 2025-12-19T21:17:26.889Z
Learnt from: CR
Repo: nerdCopter/bbl_parser PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-19T21:17:26.889Z
Learning: Applies to src/{lib.rs,parser/**/*.rs,export.rs} : Core logic in `src/lib.rs` with parser modules (`src/parser/`) and export functions (`src/export.rs`) shared by both library and CLI
Applied to files:
examples/csv_export.rsexamples/multi_flight_export.rsCRATE_USAGE.mdexamples/README.md
📚 Learning: 2025-12-19T21:17:26.889Z
Learnt from: CR
Repo: nerdCopter/bbl_parser PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-19T21:17:26.889Z
Learning: Applies to src/**/*.rs : Do not remove or modify comments unless the related code is changed; only add comments that explain code functionality, no AI instructional comments
Applied to files:
examples/csv_export.rs
📚 Learning: 2025-12-19T21:17:26.889Z
Learnt from: CR
Repo: nerdCopter/bbl_parser PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-19T21:17:26.889Z
Learning: Applies to src/**/*.rs : BEFORE ANY CODE CHANGES: Run `cargo fmt --all -- --check` to ensure formatting compliance
Applied to files:
examples/csv_export.rs
📚 Learning: 2025-12-08T21:15:02.434Z
Learnt from: nerdCopter
Repo: nerdCopter/bbl_parser PR: 0
File: :0-0
Timestamp: 2025-12-08T21:15:02.434Z
Learning: For bbl_parser reviews: nerdCopter prefers compact, single-block “outside diff” comments without nested <details> or admonitions; use flat bullets with file:line references and link a gist for overflow.
Applied to files:
CRATE_USAGE.md
📚 Learning: 2025-08-29T19:55:43.912Z
Learnt from: nerdCopter
Repo: nerdCopter/bbl_parser PR: 2
File: README.md:0-0
Timestamp: 2025-08-29T19:55:43.912Z
Learning: nerdCopter updated the bbl_parser project license from GPL-3.0-or-later to AGPL-3.0-or-later across all repository files (Cargo.toml, LICENSE, README.md) for consistency with the dual-licensing approach that includes a commercial license option.
Applied to files:
CRATE_USAGE.md
📚 Learning: 2025-12-19T21:17:26.889Z
Learnt from: CR
Repo: nerdCopter/bbl_parser PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-19T21:17:26.889Z
Learning: Applies to Cargo.toml : Feature flags `csv`, `cli`, `json`, `serde` control optional dependencies; default: `csv` + `cli`
Applied to files:
examples/README.md
🧬 Code graph analysis (1)
examples/multi_flight_export.rs (3)
src/export.rs (1)
export_to_csv(191-229)src/parser/main.rs (1)
parse_bbl_file_all_logs(6-25)examples/csv_export.rs (1)
main(15-61)
🪛 markdownlint-cli2 (0.18.1)
examples/README.md
42-42: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Build Release Binaries (macos-latest, bbl_parser-macos-x64, target/release/bbl_parser)
- GitHub Check: Build Release Binaries (ubuntu-latest, bbl_parser-linux-x64, target/release/bbl_parser)
- GitHub Check: Build Release Binaries (windows-latest, bbl_parser-windows-x64, target/release/bbl_parser.exe)
🔇 Additional comments (11)
examples/csv_export.rs (2)
3-10: Excellent clarification of single-flight behavior.The updated module documentation clearly communicates that this example exports only the first flight and guides users to the appropriate alternative for multi-flight files. This will help prevent the common mistake of using
parse_bbl_file()whenparse_bbl_file_all_logs()is needed.
20-21: Good user guidance in the CLI usage message.The added notes clearly inform users about the first-flight limitation and direct them to the multi_flight_export example for handling multiple flights. This is exactly the kind of helpful inline documentation that prevents user confusion.
examples/multi_flight_export.rs (3)
1-9: Clear module documentation distinguishing this from csv_export.The module header effectively explains the key difference between this example and csv_export.rs, making it easy for users to choose the right approach for their use case.
35-44: Good defensive programming with empty logs check.Handling the case where no logs are found prevents confusing output and provides clear feedback to the user.
47-71: Well-structured per-flight export loop.The iteration logic clearly displays metadata for each flight, exports with proper error propagation, and provides helpful status messages showing the flight number suffix. This makes it easy for users to understand what's happening during multi-flight export.
CRATE_USAGE.md (3)
5-14: Excellent upfront warning about multi-flight handling.The prominent warning table at the top of the document immediately addresses the most common source of confusion - when to use which parsing function. This placement and clarity will save users from making the mistake of using
parse_bbl_file()on multi-flight files.
69-107: Comprehensive multi-flight usage guidance.The progression from basic multi-flight usage to best practice recommendations (always use
parse_bbl_file_all_logs()) provides clear guidance for developers at different levels. The code examples are complete and immediately usable.
273-323: Outstanding flight numbering reference section.The detailed tables showing different scenarios (single flight, 3 flights with different parsing approaches) combined with suffix rules make this an invaluable quick reference. The information about zero-padded 2-digit format and automatic handling by export functions removes ambiguity.
examples/README.md (3)
5-16: Excellent Quick Start section placement.Putting the most common use cases right at the top with simple command examples makes it easy for users to get started immediately. The distinction between single-flight and multi-flight export is clear and actionable.
76-86: Clear flight numbering reference table.The table showing different scenarios and their outputs provides a quick visual reference that complements the detailed documentation in CRATE_USAGE.md. This helps users quickly understand which function to use for their situation.
315-346: Valuable CLI vs Library distinction.The new section clearly explains when to use the CLI binary versus the library API, along with concrete examples of installation and usage. This addresses a common point of confusion for users trying to understand the relationship between the CLI tool and the library.
- Added 'text' language identifier to multi_flight_export example output (line 42) - Added 'text' language identifier to export_demo example output (line 176) - Improves syntax highlighting and markdown linting compliance - All code blocks now properly labeled: bash, rust, or text
1 participant
Overview
Comprehensive documentation and example improvements addressing user confusion about multi-log API usage, example organization, and feature completeness.
Changes
1. Multi-Log API Clarity
multi_flight_export.rsexample demonstrating correctparse_bbl_file_all_logs()usagecsv_export.rswith clear warnings about first-flight-only behaviorCRATE_USAGE.mdwith prominent warning section and flight numbering documentation2. Documentation Consolidation
3. Feature Status Corrections
4. CLI vs Library Clarification
bbl_parserCLI binary is (src/main.rs, part of the crate)5. Example Consistency
6. Examples/README.md Updates
Commits
6dda59b- docs: Clarify multi-log API and add multi_flight_export example88c3d6e- docs: Remove export_demo duplication in examples/README.md2171dc8- docs: Remove csv_export duplication in examples/README.mdb2a1cbf- docs: Clarify CLI vs Library API in examples/README.md78d114d- docs: Correct GPS and Event export implementation status4f519a7- docs: Update multi_export status to fully functionalabf08f0- refactor: Simplify output logic in multi_flight_export.rs173b480- docs: Add status indicator to export_demo sectionTesting
All examples have been tested and verified:
Benefits
parse_bbl_file()andparse_bbl_file_all_logs()Breaking Changes
None. All changes are documentation and example improvements. No API changes.
Related Issues
Addresses the test_crate API usage issue and improves onboarding for new crate users.
Summary by CodeRabbit
Documentation
Examples
✏️ Tip: You can customize this high-level summary in your review settings.