Skip to content

docs: guide readers between JLedGroup and JLedRefGroup, drop deferred-feature promise#175

Closed
jandelgado wants to merge 1 commit into
masterfrom
group_documentation_update
Closed

docs: guide readers between JLedGroup and JLedRefGroup, drop deferred-feature promise#175
jandelgado wants to merge 1 commit into
masterfrom
group_documentation_update

Conversation

@jandelgado

@jandelgado jandelgado commented Jul 19, 2026

Copy link
Copy Markdown
Owner

Documentation only, no code changes.

What

1. New "When to use what?" section in the group chapter, so readers can pick a group type without reading both subsections first. It leads with JLedGroup as the default and frames JLedRefGroup around the decision that drives the choice: whether you already keep your LEDs as named variables.

In that case JLedRefGroup is substantially more memory efficient, because a JLedGroup stores its own copy of every LED, so a named LED ends up stored twice. Measured on atmega328p at -Os, six named JLed objects plus the group:

6 named JLed flash RAM
JLedGroup 3096 358
JLedRefGroup 2888 198

Per element that is 54 bytes (24 for your named object + 30 for the JLedAny copy) against 28 (24 + a 4-byte JLedRef).

The section states this as a conditional benefit rather than a blanket one, because it does not hold when the LEDs live only inside the group and you never touch them individually. There the two are close to a wash, and the sign even flips with LED type, since sizeof(JLedRef) + sizeof(JLedHD) (32) exceeds sizeof(JLedAny) (30):

6 LEDs, group-only JLedGroup RAM JLedRefGroup RAM
JLed 214 198
JLedHD 214 222

2. Removed two forward-looking promises about per-element events:

  • "Per-element events (reacting to individual LEDs within a group) are not yet supported."
  • "Full-depth, per-leaf visibility is planned via a future per-element callback."

That feature is deferred with no timeline, so the README should not advertise it.

3. Documented what works today in its place. To react to a single LED inside a group, keep it as a named variable and watch its own state across the Update() call:

bool was_running = led1.IsRunning();
group.Update();
if (was_running && !led1.IsRunning()) {
    Serial.println("led1 finished");
}

Verified against the host test mocks: this fires exactly once, on the tick led1 completes, while other group members keep running.

Notes

  • Table of contents updated; all internal anchors resolve.
  • One pre-existing broken link, [Percentage](#percentage) at line 644, is left alone to keep this PR focused. There is no matching heading in the file, so it needs a decision about where it should point rather than a mechanical fix.

@coveralls

coveralls commented Jul 19, 2026

Copy link
Copy Markdown

Coverage Status

coverage: 97.976%. remained the same — group_documentation_update into master

@jandelgado
jandelgado force-pushed the group_documentation_update branch from 8358a68 to b0e8090 Compare July 19, 2026 14:02
@jandelgado
jandelgado force-pushed the group_documentation_update branch from b0e8090 to 428a348 Compare July 19, 2026 14:16
@jandelgado jandelgado closed this Jul 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants