Come documentare un protocollo di comunicazione in cima alle code e ai canali dei messaggi?

Sono l'autore di pg_message_queue, un sistema channel / queue molto leggero in PostgreSQL progettato per facilitare l'integrazione a livello di database. I messaggi possono quindi essere inoltrati a una coda di messaggi più pesanti, o simili, oppure possono essere elaborati. Il caso d'uso è per cose come "Voglio inviare un'e-mail dal database" e aiuta a risolvere il problema di PostgreSQL senza problemi di elaborazione transazionale davvero difficili che potrebbero risultare.

La nostra documentazione è link

Non dirò che è la migliore documentazione là fuori, ma è sufficiente per il nostro caso d'uso. Confronta con link che è la documentazione di rabbitmq e vedrai in che modo sono diversi i requisiti della documentazione.

Tuttavia, come tutti i documenti, mantieni il tuo pubblico e utilizzi il caso e analizzalo concettualmente e in modo programmatico.

Modifica Ok, vedo ciò che ho frainteso. Suggerirei di iniziare almeno con una descrizione della documentazione tecnica. Se ce l'hai da qualcun altro, bene. In caso contrario, fornisci almeno una descrizione di ciò che un manuale del programmatore tecnico dovrebbe coprire.

Mi sembra che tu stia cercando di documentare un protocollo di rete piuttosto che un'API. Scusa, l'ho letto e ho perso quella parte. Non mi è ancora chiaro se questo è diretto su TCP, o su HTTP o qualcos'altro. Nella misura in cui stai riutilizzando altri protocolli, il lavoro è più semplice.

In ogni caso, dividerei la documentazione in tre sezioni. Il primo riguarderebbe la struttura dei messaggi in generale. Ciò includerebbe intestazioni, specifiche del corpo del messaggio, ecc. Ma sarebbe abbastanza generale da fornire un riferimento per la sezione 2.

La sezione 2 coprirebbe le specifiche per ciascun tipo di messaggio. Di nuovo dipende da cosa stai riutilizzando esattamente la profondità di cui hai bisogno.

La sezione 3 fornirebbe esempi su come la comunicazione funzionerebbe usando insiemi di messaggi mocked up.

Ho usato pi-calculus per documentare e analizzare i processi di alto livello. Non esiste un linguaggio standard per il pi-calcolo, ma per uno strumento che ho scritto ho usato un semplice linguaggio a una riga per passo atomico, che sarebbe simile a qualcosa:

process Client
    # initialise client process with the channel to subscribe to 
    recv self Init ( channel1 : channel, queue1 : channel ) 
    # send request to server
    send queue1 RequestForStream ( channel1 )
    # bind channel in response to channel2
    recv channel1 StreamResponse ( channel2 : channel )

    loop:
    choice
        # either receive a notification or stop
        recv channel2 Notification ()
            goto loop
        recv channel2 Stop()
            stop

process Server
    new channel2
    # wait for request
    recv self RequestForStream ( client : channel )
    # send response to client with channel2 to send
    send client StreamResponse ( channel2 ) 
    # send notifications on channel2
    send channel2 Notification ()
    send channel2 Notification ()
    send channel2 Stop ()
    stop


# test
process Test
    c := start Client
    s := start Server

    send c Init ( c, s )
    stop


start Test

le parti extra stop ci sono perché lo strumento è in grado di rilevare deadlock e razze livellate.