[docs]: Marble Diagrams improvements

[BioPhoton]

Documentation Related To Component:

Marble Diagrams

Please check those that apply

• [ ] typo
• [ ] documentation doesn't exist
• [x] documentation needs clarification
• [ ] error(s) in example
• [ ] needs example

Description Of The Issue

Some of the diagrams are hard to understand. The list above contains little changes would serve a lot more value imho.

• all operators with higher-order completion All completions are in are vertically centered. This makes it very hard to see if a interna or external stream triggers

• all operators overlaping notifications completion and value at the same frame works only for very simple situations i.e. elementAt

• all operators with side effects The blue border is meaningless i.e. tap or finalize

• all operators scheduling The blue border is meaningless i.e. share. In addition to that, it is the same way how side-effects are displayed. This is maybe leading to wrong assumptions.

• all operators with projection functions the internal psudo code is hard to understand i.e. concatMap

• all operators with triggers there could be more distance between incoming values and the trigger notifications. ATM hard to see as they are also sometimes directly under each other. i.e. throttling or buffer/window operators

• all operators higher-order It is very hard to follow the imaginary vertical line that maps internal values to the timeline.

• audit Could show the timer observable multiple times as ATM it is very hard to make the assumption that it repeats.

• bufferTime shows no timer interval. Could implement at least something as an audit does

• combineAll ATM it is very hard to make assumptions about the transparent streams

• concatAll Both, transp arent streams and diagonal completion are hard to understand

• concatAll Both, transparent streams and diagonal completion are hard to understand

• defer It would be helpful to show that the subscription triggers it

• delayWhen Instead of the param name "resultSelector", psudo code would be more helpful

• exhaust It's unclear if the input or the internal stream triggers the completion

• expand Internal streams 4 and 8 are missing

• generate Adding the completing like in from would be helpful

• pairs Adding the completing like in from would be helpful

[timdp]

This heavily relates to #5019. As explained under that PR, part of why I built my own diagram generator is because I wanted the ability to annotate diagrams. In fact, my code already contains some features that are currently unused by the PR. I went for feature parity first.

[BioPhoton]

@timdp Nice! :) :) 👍 Do you think you can align it with my suggestions here?

I collected all the problems in a design system over the last 1.5 years. It is able to express all operations or building blocks.

[timdp]

I came across your design system when I was looking for an existing diagram generator. It looked/looks very professional, and I think it's an improvement over the current style. However, I don't think it's being used for any official resources yet? Or did I miss something?

My side of things is that I originally needed a reliable way to generate relatively simple marble diagrams for a talk. That's why I built Swirly. Later on, I decided to support the ASCII marble diagram syntax used in the tests. That got me thinking about using Swirly to render the diagrams in the docs as well, so I made some tweaks to simplify that scenario. And then I did a bunch of refactoring, because that's how these things escalate.

Now, Swirly could be extended with all the changes you're proposing. However, especially given that it's just a side project at this point, I'm more inclined to focus my efforts on providing value to the community by making sure it's compatible with the existing resources first. That said, I think most of the design system, if not all of it, could be treated as incremental improvements to Swirly later on.