canonical / canonical/operator
Expose the testing _Event.deferred docs
- Dominant language
- Python
- Stars
- 267
- Forks
- 136
- Avg merge
- 1d 22h
- Merged PRs (30d)
- 28
Description
Because `scenario._Event` is private, it doesn't show up in the API reference documentation. Users shouldn't be subclassing `_Event` and shouldn't be creating them other than via `ctx.on`, so it is nice if the class does remain private.
However, when you have an `_Event`, we provide a `deferred()` method on it that is meant for use. This will show up in `help()` and in IDE tips but is missing from our published API reference docs, since it's on the private class.
We should solve this somehow. Maybe we go back to having a top-level `deferred()` function instead of attaching it to `_Event`? (We'd need to keep the existing one for backwards compatibility, but it could just call the public one). Maybe the `deferred()` docs can be on `CharmEvents` or somewhere similar?
Contributor guide
Research direction
Start by reviewing scenario._Event, its deferred() method, ctx.on, and the existing CharmEvents documentation path. Compare how help(), IDE tips, and the published API reference expose deferred(). Done means users can find the supported deferred() documentation in the API reference without making the private _Event class public, while preserving the existing behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 38/100