docs(notifier): Document PublishKit and deprecate NotifierKit/SubscriberKit #7429
Conversation
| The code is still correct. However, Alice and Bob may each have missed either or both | ||
| of the non-final values due to NotifierKit’s lossy nature. | ||
|
|
||
| On yet another hand (🤷), the `subscriber` of a Publication includes both a |
| It is also possible to use `subscribeEach` for forward-lossless consumption of a `subscriber` | ||
| or `subscription`, and `subscribeLatest` for lossy consumption of a `subscriber` or `notifier`. |
There was a problem hiding this comment.
IMO, this should be the headline and not just a footnote. I think we should deprecate the getSharable*Internals() and observeIterat* manipulation and just point to using these adaptors with for-await-of, which has much clearer semantics.
There was a problem hiding this comment.
Do you have something concrete in mind? The current structure from this PR looks like
- PublishKit and Related Types
- Distributed Asynchronous Iteration
- Type Differences
- Lossiness
- NotifierKit
- SubscriptionKit
- PublishKit
- Use Cases
- Example
- Distributed Operation
- Summary
subscribeEach and subscribeLatest are mentioned in Type Differences and Example and Distributed Operation.
| asynchronous value sequences, the *PublishKit*, along with similar but | ||
| deprecated types *NotifierKit* and *SubscriptionKit*. |
There was a problem hiding this comment.
Is NotifierKit deprecated? It's not marked so if this PR also making that change it should include the @deprecated tag.
There was a problem hiding this comment.
Yes, AFAIK (search Slack for "deprecated notifier"). Where would you expect to see @deprecated?
| @@ -1,59 +1,127 @@ | |||
| # NotifierKits and SubscriptionKits | |||
| # PublishKit and Related Types | |||
There was a problem hiding this comment.
I think the primary use of this doc will be for someone what wants to understand the recommended way to use the package. The deprecated aspects are for understanding code you encounter but won't write.
As such I suggest having the README clearly document non-deprecated PublishKit (and NotifierKit?) but only mention the deprecated ones. Expect someone to understand non-deprecated before learning about them. Then have a separate document for understanding the older types, including how they work and why they were deprecated.
There was a problem hiding this comment.
I think this is currently the place to document all three, and am trying to minimize disruption to just what is necessary for including publish kits (especially since endojs/endo#1035 will prompt further changes).
There was a problem hiding this comment.
Given the goal to change
just what is necessary for including publish kits (especially since endojs/endo#1035 will prompt further changes
I'm happy to approve this PR to get it merged.
gibson042
force-pushed
the
gibson-2023-04-publishkit-docs
branch
from
1d2e698 to
979a0ec
Compare
Description
This is the long-overdue update of the notifier package README to deprecate NotifierKit and SubscriberKit in favor of PublishKit.
Security Considerations
n/a
Scaling Considerations
n/a
Documentation Considerations
https://docs.agoric.com/guides/js-programming/notifiers.html should be updated accordingly.
Testing Considerations
n/a