Dokumentowanie przepływów kodu za pomocą Syreny

Ukończone

Oprócz pisania tekstu lub kodu Notesy Wielojęzyczne może renderować diagramy syren.

Syrena to język, który umożliwia wyrażanie różnych typów wykresów i diagramów przy użyciu tekstu. Notesy Wielojęzyczne może przyjmować kod napisany dla Syreny i renderować go. Dobrym przypadkiem użycia jest pokazanie, jak działa kod.

Przyjrzyjmy się przykładowi, który dokumentuje przepływ zakupu.

Wyobraź sobie, że chcesz udokumentować sposób działania interfejsu API podczas przetwarzania płatności z zakupu. Oto kod Mermaid z metody wyewidencjonowania, w której kod jest wywoływany w krokach w różnych warstwach:

class CheckoutService {
    private \_cart;
    private \_cardService;
    private \_shippingService;

    public CheckoutService(
        Cart cart,
        CardService cardService,
        ShippingService shippingService) {
        this.\_cart = cart;
        this.\_cardService = cardService;
        this.\_shippingService = shippingService;
    }

    public void Checkout() {
        if(this.\_cart.GetTotal() > 0) {
            let responseCode = this.\_cardService.Charge(new Card("Visa", "1234"));

            if (responseCode != 200) {
                throw new Exception("Unable to charge card");
            }
        
            this.\_shippingService.Ship("123 Main St", this.\_cart);
        }
    }
}

Chcesz szybko pokazać wizualizację, jak działa ten kod, więc użyjesz kodu syrenki w następujący sposób:

sequenceDiagram
    CheckoutService ->> CardService: Charge(card)
    CardService -->> CheckoutService: OK, payment cleared
    CheckoutService -) ShippingService: Ship(cart)
    ShippingService -->> CheckoutService: OK, "shipping cart content"

Na koniec, umieszczając kod Syreny w komórce kodu, otrzymujesz miłe renderowanie w następujący sposób:

Poprzednia wizualizacja z renderowania Syrenki jest łatwiej zrozumieć na pierwszy rzut oka, a także udostępnić ją nietechnicznych uczestnikom projektu, aby pokazać, jak działa system.