Document buffer(policy:) and mapError(_:), fix docs catalog gaps - #447
Open
maxches99 wants to merge 1 commit into
Open
Document buffer(policy:) and mapError(_:), fix docs catalog gaps#447maxches99 wants to merge 1 commit into
maxches99 wants to merge 1 commit into
Conversation
The README algorithm catalog and the DocC topic list did not cover every public algorithm: * `buffer(policy:)` had no guide, no README entry and no topic entry. * `mapError(_:)` had no guide and no README entry. * `FlatMapLatest` had a guide but was missing from the topic list, so it did not appear in the rendered documentation. * `Chunked.md` linked to `AsyncChunksOfCountAndSignalSequence.swift`, which does not exist - the type is `AsyncChunksOfCountOrSignalSequence` - and listed `AsyncChunkedOnProjectionSequence.swift` twice. Add the two missing guides, list them along with FlatMapLatest in the topic list, add the two missing README entries and correct the Chunked source links.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
The algorithm catalog in
README.mdand the topic list inAsyncAlgorithms.mdhave drifted from the set of algorithms the package actually vends, so several public algorithms are not reachable from either the README or the rendered DocC documentation.Concretely, on
main:buffer(policy:)has no guide, no README entry and no topic entry.mapError(_:)has no guide and no README entry.FlatMapLatesthas a guide, but it is missing from the topic list, so it is not rendered.Chunked.mdlinks toAsyncChunksOfCountAndSignalSequence.swift, which 404s — the type isAsyncChunksOfCountOrSignalSequence— and listsAsyncChunkedOnProjectionSequence.swifttwice.Fixes #300.
Addresses the documentation gap tracked in #408 (the
shareREADME entry itself is covered by #443 — see the note below).The
Chunked.mdlink is the same class of breakage as #284, which was fixed forIntersperse.mdbut missed here.Modifications
Guides/Buffer.mddocumentingbuffer(policy:)and the fourAsyncBufferSequencePolicycases.Guides/MapError.mddocumenting the twomapError(_:)overloads.<doc:Buffer>,<doc:MapError>and the missing<doc:FlatMapLatest>to the topic list inAsyncAlgorithms.md.buffer(policy:)andmapError(_:)to the README catalog.Chunked.mdsource links.The buffering behaviour described in
Buffer.mdwas checked against the state machines rather than transcribed from the doc comments:bufferingLatest(_:)drops the oldest buffered element,bufferingOldest(_:)drops the incoming element, and a limit of0bypasses buffering entirely (AsyncBufferSequence.makeAsyncIterator()selects the transparent storage). Note that the doc comment onbuffer(policy:)refers to the policy asbufferingNewest, which is the internal case name; the guide uses the public spellingbufferingLatest.Effects.mdalready listsAsyncBufferSequence, andAsyncMapErrorSequenceis internal, so that table is unchanged.Result
Every guide in the catalog is reachable from the topic list, every
<doc:>reference resolves to a file inGuides/, every source and test link in every guide points at a file that exists, andbuffer(policy:)andmapError(_:)are discoverable from the README.Note on #443
#443 is approved and touches the same README section within a couple of lines of these two additions, so this will likely need a trivial conflict resolution. Happy to rebase once #443 lands — just let me know if you would rather have it that way round.