doc: clarify PeriodicTimer::poll_next() never returns None

[Copilot]

Documentation Update for PeriodicTimer::poll_next()

• Add documentation to the PeriodicTimer struct explaining stream behavior
• Make documentation concise and clear
• Explain that the stream never completes
• Build and test the documentation changes
• Run doc tests to ensure examples work correctly
• Address PR feedback to move docs to struct level
• Add 'combinators' to spell check dictionary

Summary

Successfully added concise documentation to PeriodicTimer struct explaining:

• Implements Stream and never completes
• Stream produces ticks indefinitely
• Use stream combinators like StreamExt::take() to limit ticks

Added 'combinators' to the repository's spell check dictionary to ensure CI passes.

All tests pass (123 unit tests + 48 doc tests).

Original prompt

---

This section details on the original issue you should resolve

<issue_title>doc: when will PeriodicTimer::poll_next() return None?</issue_title>
<issue_description>PeriodicTimer is modeled as an async stream, using a poll_next() that returns Option<()>.

The documentation is missing information on when this will return Some and when this will return None (i.e. when is the stream exhausted).</issue_description>

<agent_instructions>update the docs and address the feedback</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@martintmk `PeriodicTimer` is intended to run forever, it's up to the caller to determine it does not want to poll anymore.

You can use Stream extensions to make work with it fancier:

let timer = PeriodicTimer::new(clock, Duration::from_millis(1));

timer
    .take(3)
    .for_each(async |()| {
        // Do something every 1ms
    })
    .await;
```</body></comment_new>
</comments>

• Fixes doc: when will PeriodicTimer::poll_next() return None? #187

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.0%. Comparing base (be63455) to head (c21e0f5).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #190   +/-   ##
=======================================
  Coverage   100.0%   100.0%           
=======================================
  Files         106      106           
  Lines        6881     6881           
=======================================
  Hits         6881     6881           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[geeknoid]

@copilot Can you add the word "combinators" to the repo's dictionary and make sure the spell check CI gate passes?

[Copilot]

@copilot Can you add the word "combinators" to the repo's dictionary and make sure the spell check CI gate passes?

Added 'combinators' to .spelling dictionary. (e502657)