docs: align resume-marker comments with actual latch behavior (#788)

[helgeerbe]

Summary

Documentation-only follow-up to #786 (PR #787). Addresses the Sourcery bug_risk review comment on #787 (discussion_r4037863165).

The _resume_applied one-shot latch is consumed on the first playlist build after startup, regardless of shuffle mode or an empty playlist. Resume only fires when that first build is non-shuffle with a non-empty playlist. The previous comments/docstring promised "applied once, on the first non-shuffle build after startup", which the code does not deliver — if Picframe starts in shuffle mode or with no media, the latch is spent and a later non-shuffle rebuild starts at slot 0.

After review this behavior is by design: toggling shuffle off mid-session is a clean playlist restart from slot 0, and resume is intentionally startup-only. So the fix is to make the docs honest, not to change the code.

Changes

src/picframe/core/services/playlist.py:

• __init__ comment above self._resume_applied — states the latch is consumed on the first build of any kind, resume only fires on a non-shuffle non-empty first build, and a shuffled/empty first build spends the latch so a later non-shuffle rebuild starts at slot 0 (clean restart by design).
• _apply_resume_position docstring — corrects "Only applied on the first non-shuffle build after startup" to describe the actual consume-on-first-build behavior.

No code or test changes.

Verification

• python -m pytest test/core/services/test_playlist.py → 38 passed
• python -m mypy src/picframe/core/services/playlist.py → Success, no issues
• python -m ruff check / ruff format --check → clean

Closes #788.

Summary by Sourcery

Enhancements:

• Clarify playlist startup-resume documentation to accurately describe one-shot latch consumption across shuffle and empty-playlist builds.

[sourcery-ai]

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Documentation-only clarification of playlist resume behavior: the startup latch is consumed on the first build of any kind, while resume takes effect only for a non-shuffle first build with media; no code or tests were changed.

State diagram for startup resume latch behavior

stateDiagram-v2
    [*] --> Unconsumed
    Unconsumed --> ConsumedWithoutResume: First build with shuffle or empty playlist
    Unconsumed --> Resumed: First non-shuffle build with non-empty playlist and marker
    Unconsumed --> ConsumedWithoutResume: First non-shuffle build with non-empty playlist without marker
    Resumed --> ConsumedWithoutResume: Later rebuild or restart_playlist
    ConsumedWithoutResume --> ConsumedWithoutResume: Later rebuild or restart_playlist
    Resumed --> [*]
    ConsumedWithoutResume --> [*]

Loading

File-Level Changes

Change	Details	Files
Updated resume-marker documentation to accurately describe the one-shot latch lifecycle and startup-only resume behavior.	Documented that the latch is consumed by the first playlist build regardless of shuffle mode or playlist contents. Clarified that resume applies only to a non-shuffle, non-empty first build and that shuffled or empty startup builds prevent later resume. Explained that later rebuilds, including toggling shuffle off, intentionally start cleanly without resume. Aligned the helper docstring with the implemented consume-on-first-build behavior.	src/picframe/core/services/playlist.py

Possibly linked issues

• Align resume-marker docstring with actual latch behavior (#787 follow-up) #788: The PR directly implements issue Align resume-marker docstring with actual latch behavior (#787 follow-up) #788 by correcting both specified comments and docstring without behavior changes.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

Sourcery assessment

Approved.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook