More accessible docs

[IdoPractical]

Hi, I wanted to take a look at the topology diagram in the docs folder, but it seems like Monodraw, the tool used to view it, is only available for Mac. Unfortunately, I don't currently have access to a Mac. Do you mind adding an image of the diagram for those who can't use Mac with Monodraw? Thanks!

[jamwaffles]

Hey, apologies for not having the best compatibility for that file. However, opening it again just now, it doesn't contain anything particularly useful. The exact content is these lines, posted here for posterity:

┌─────────────┐
│   Master    │
│     #0      │
│             │
└─────────────┘
       ▲
       ║
       ╚0▶┌────────────┐      ┌────────────┐      ┌────────────┐──┐
          │   EK1100   │      │   EL2004   │      │   EL3004   │  │
          │     #1     │◀3══0▶│     #3     │◀3══0▶│     #4     │  │
          │            │      │            │      │            │  │
       ╔1▶└────────────┘      └────────────┘      └────────────┘◀─┘
       ║
       ║  ┌────────────┐──┐
       ║  │  LAN9252   │  │
       ╚0▶│     #5     │  │
          │            │  │
          └────────────┘◀─┘

I'm going to remove the Monodraw source as it's not useful and clearly confusing :)

[HolgerJeromin]

JFYI: such diagrams can be made with https://mermaid.js.org/ which can be included in markdown files and are live rendered in the github interface when viewing the doc.

[jamwaffles]

Indeed :). I'm using Mermaid for some of the internal doc comments. Even though docs.rs won't render them (yet?), they can still be pasted into a Mermaid renderer.

[HolgerJeromin]

Hmm, extracting the mermaid code from mod.rs in a sibling mod.md feels ugly... But this is soo nice :-)

 flowchart TD
    FrameState::None -->|"alloc_frame()\nFrame is now exclusively (guaranteed by atomic state) available to calling code"| FrameState::Created
    FrameState::Created -->|populate PDU command, data| FrameState::Created
    FrameState::Created -->|"frame.mark_sendable()\nTHEN\nWake TX loop"| FrameState::Sendable
    FrameState::Sendable -->|TX loop sends over network| FrameState::Sending
    FrameState::Sending -->|"RX loop receives frame, calls pdu_rx()\nClaims frame as receiving"| FrameState::RxBusy
    FrameState::RxBusy -->|"Validation/processing complete\nReceivingFrame::mark_received()\nWake frame waker"| FrameState::RxDone
    FrameState::RxDone -->|"Wake future\nCalling code can now use response data"| FrameState::RxProcessing
    FrameState::RxProcessing -->|"Calling code is done with frame\nReceivedFrame::drop()"| FrameState::None