Add Parameter Group system documentation for developers#11271
Merged
sensei-hacker merged 1 commit intoiNavFlight:maintenance-9.xfrom Feb 8, 2026
Merged
Conversation
Document INAV's PG system to help developers understand: - How the compile-time registry works using linker sections - When to increment PG version numbers (struct layout changes) - How to register new parameter groups with proper macros - Version validation mechanism in pgLoad() Includes practical examples based on actual code (blackbox PG) and references to related PRs for context.
Contributor
PR Compliance Guide 🔍All compliance sections have been disabled in the configurations. |
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
Comment on lines
+52
to
+65
| ```c | ||
| void pgLoad(const pgRegistry_t* reg, int profileIndex, | ||
| const void *from, int size, int version) | ||
| { | ||
| pgReset(reg, profileIndex); // Always reset to defaults first | ||
|
|
||
| if (version == pgVersion(reg)) { | ||
| // Only copy if versions match | ||
| const int take = MIN(size, pgSize(reg)); | ||
| memcpy(pgOffset(reg, profileIndex), from, take); | ||
| } | ||
| // If version mismatch: defaults remain, no corruption | ||
| } | ||
| ``` |
Contributor
There was a problem hiding this comment.
Suggestion: Update the documentation snippet to show basic input validation (e.g., from != NULL and size > 0) before calling memcpy, since real callers may pass invalid pointers/sizes; keep a safe fallback of “defaults only” when validation fails. [Learned best practice, importance: 6]
Suggested change
| ```c | |
| void pgLoad(const pgRegistry_t* reg, int profileIndex, | |
| const void *from, int size, int version) | |
| { | |
| pgReset(reg, profileIndex); // Always reset to defaults first | |
| if (version == pgVersion(reg)) { | |
| // Only copy if versions match | |
| const int take = MIN(size, pgSize(reg)); | |
| memcpy(pgOffset(reg, profileIndex), from, take); | |
| } | |
| // If version mismatch: defaults remain, no corruption | |
| } | |
| ``` | |
| ```c | |
| void pgLoad(const pgRegistry_t* reg, int profileIndex, | |
| const void *from, int size, int version) | |
| { | |
| pgReset(reg, profileIndex); // Always reset to defaults first | |
| if (version == pgVersion(reg) && from != NULL && size > 0) { | |
| // Only copy if versions match and input is valid | |
| const int take = MIN(size, pgSize(reg)); | |
| memcpy(pgOffset(reg, profileIndex), from, take); | |
| } | |
| // Otherwise: defaults remain, no corruption | |
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
User description
Summary
Add comprehensive developer documentation for INAV's Parameter Group (PG) system to help developers understand when to increment PG version numbers and how to register parameter groups correctly.
Changes
docs/development/parameter_groups/README.mdwith practical guidepgLoad()Key Topics Covered
__pg_registry_start/end)pgLoad()resets to defaults on mismatchPG_REGISTER_WITH_RESET_TEMPLATE, etc.)Documentation Approach
parameter_group.h/c)Related Context
PR Type
Documentation
Description
Add comprehensive Parameter Group system documentation for developers
Explains compile-time registry using linker sections and version validation
Documents when to increment PG version numbers with practical examples
Provides complete working examples and registration macro reference
Diagram Walkthrough
File Walkthrough
README.md
Parameter Group system developer guidedocs/development/parameter_groups/README.md
architecture
registry
pgLoad()and when to incrementversions
accessing parameter groups
increment examples