docs: port real LVGL function docs from the official guide - #5
Closed
pfeerick wants to merge 1 commit into
Closed
Conversation
The firmware has zero /*luadoc*/ annotations for any of the 45 lvgl.*
Lua bindings (radio/src/lua/api_colorlcd_lvgl.cpp), so this repo's
source-extraction pipeline had nothing to extract for the LVGL
section and fell back to a generic template for all 42 constructor
pages that have an official-guide counterpart: a bare "params (table)
object definition table" placeholder, an untyped bullet list of key
names, and -- on every single page -- "Since: 3.0.0", which is wrong.
The official EdgeTX/lua-reference-guide's LVGL docs are not guesswork
either way: they were written by GitHub user phil.a.mitchell, who is
almost certainly the same person as philmoz, the primary author (19
of 22 commits) of api_colorlcd_lvgl.cpp itself. That content has full
parameter tables (name/type/description/default), return values,
behavioral notes, and real per-function "Introduced in 2.11.0" style
version history -- verified accurate against the firmware source
through the v2.11.7 tag (spot-checked: the CHOICE constant spelling
fix and the borderPad/align/menu/edited property additions are all
already correctly reflected there).
This ports all 42 matching function pages from
EdgeTX/lua-reference-guide's edgetx_2.11 branch
(lua-api-reference/lvgl-for-lua/lvgl.*.md) into this repo's page
format (H1 + syntax + description, Parameters table, Returns,
Availability, Notes, Source), fixing two source typos along the way
rather than porting them forward: a missing '(' on ~28 "create an
object" syntax lines (e.g. "lvgl.arc\[parent]..." ->
"lvgl.arc([parent]...") and a doubled-brace typo on lvgl.build's
syntax line.
Not touched:
- lvgl-close.md, lvgl-disable.md, lvgl-enable.md: real functions
(confirmed via LROT_FUNCENTRY in current firmware) added after the
official guide's content was written, with no official counterpart
to port from. They keep their existing stub content.
- website/md-docs/programming/core-concepts/lvgl-for-lua.md and
website/md-docs/api-overview/constants/lvgl-constants.md: unlike
the per-function pages, these were already good hand-written
content covering the same ground as the official guide's
overview.md/api.md/constants.md/examples.md, including the same
2.11.4/2.11.5 version callouts. No changes needed.
Known drift: ~40 commits have landed on main since the v2.11.7 tag
touching api_colorlcd_lvgl.cpp / lua_lvgl_widget.cpp -- real
additions/fixes (e.g. negative rectangle width/height, further
choice/textEdit value-setting capability, additional arc properties)
not reflected in this port, since the source it's built from is
itself a snapshot verified only through v2.11.7. Closing that gap
needs either a fresh diff pass against current main or, better, the
firmware author adding real /*luadoc*/ annotations to
api_colorlcd_lvgl.cpp so this pipeline can extract it directly instead
of another manual GitBook-to-page port.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015yCHydHbzZYCKpav38SonD
Closed
10 tasks
Collaborator
Author
|
Superseded: the goal here (accurate LVGL docs instead of the placeholder "Since: 3.0.0" content) is now achieved via real extraction instead of a manual port. EdgeTX/edgetx#7771 adds proper /luadoc/ annotations for all 45 lvgl.* functions, and the pipeline can now parse them correctly (commits a408cce, 5c5014b on edgetx_2.12 — the indentation-anchored regex bug and the flattened-bullet-list table rendering that were blocking this). Once #7771 lands and the extracted content replaces the current hand-preserved lvgl-*.md pages, this manual port is no longer needed — the whole point of #7771 landing is to make ports like this one unnecessary going forward. |
pfeerick
added a commit
that referenced
this pull request
Sep 9, 2026
Re-extracted from EdgeTX/edgetx branch 2.12 at 8718d2473a (the squash merge of #7771, "add luadoc annotations for the LVGL Lua API"): 153 -> 198 items, all 45 real. The 44 hand-preserved flat lvgl-*.md pages (ported from the official guide, since firmware had zero LVGL annotations at all -- see prior HANDOFF.md entries) are replaced with real nested display-lvgl/<item>.md pages generated the same way as every other group now; the old flat files are removed, not left as orphans. Both #5 (the manual port) and #7 (the @common/@commonparams support this depended on, already ported separately) on JimB40/lua-reference-guide are closed as superseded by this. docs-system/generated/api-model.local.json, REAL-EXTRACTION-NOTES.md (both copies), and HANDOFF.md updated to match. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HLXbKn4rY3NihRnqH89jmD
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
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.
Summary
The firmware has zero
/*luadoc*/annotations for any of the 45lvgl.*Lua bindings (radio/src/lua/api_colorlcd_lvgl.cpp), so this repo's source-extraction pipeline had nothing to extract for the LVGL section and fell back to a generic template for all 42 constructor pages that have an official-guide counterpart: a bareparams (table)placeholder, an untyped bullet list of key names, and — on every single page —Since: 3.0.0, which is factually wrong.The official
EdgeTX/lua-reference-guide's LVGL docs aren't guesswork either way: they were written by GitHub userphil.a.mitchell, who is almost certainly the same person asphilmoz, the primary author (19 of 22 commits) ofapi_colorlcd_lvgl.cppitself — i.e. the implementer wrote the docs. That content has full parameter tables (name/type/description/default), return values, behavioral notes, and real per-function "Introduced in 2.11.0"-style version history. I spot-checked it against current firmware and confirmed it's accurate through the v2.11.7 tag: theCHOICEconstant spelling (firmware had aCHOIDEtypo at one point, fixed later — the docs already show the correct spelling) and theborderPad/align/menu/editedproperty additions (2.11.4–2.11.6) are all already correctly reflected there.This ports all 42 matching function pages from
EdgeTX/lua-reference-guide'sedgetx_2.11branch (lua-api-reference/lvgl-for-lua/lvgl.*.md) into this repo's page format (H1 + syntax + description,## Parameterstable,## Returns,## Availability,## Notes,## Source). Fixed two source typos along the way rather than porting them forward: a missing(on ~28 "create an object" syntax lines (e.g.lvgl.arc\[parent]...→lvgl.arc([parent]...) and a doubled-brace typo onlvgl.build's syntax line.Not touched:
lvgl-close.md,lvgl-disable.md,lvgl-enable.md— real functions (confirmed viaLROT_FUNCENTRYin current firmware) added after the official guide's content was written, with no official counterpart to port from. Left as-is.programming/core-concepts/lvgl-for-lua.mdandapi-overview/constants/lvgl-constants.md— unlike the per-function pages, these were already good, hand-written content covering the same ground as the official guide'soverview.md/api.md/constants.md/examples.md, including the same 2.11.4/2.11.5 version callouts. No changes needed.Known drift: ~40 commits have landed on
mainsince thev2.11.7tag touchingapi_colorlcd_lvgl.cpp/lua_lvgl_widget.cpp— real additions/fixes (e.g. negative rectangle width/height, further choice/textEdit value-setting capability, additional arc properties) not reflected in this port, since the source it's built from is itself only verified throughv2.11.7. Closing that gap needs either a fresh diff pass against currentmain, or better, the firmware author adding real/*luadoc*/annotations toapi_colorlcd_lvgl.cppso this pipeline can extract it directly instead of another manual port.Test plan
CHOICEspelling andborderPad/align/menu/editedversion callouts against current firmware to confirm the ported content is accurate through v2.11.7mkdocs build --strict -f mkdocs.yml— exit 0, zero warningsmkdocs build --strict -f mkdocs.dev.yml— exit 0, zero warnings🤖 Generated with Claude Code
https://claude.ai/code/session_015yCHydHbzZYCKpav38SonD