[Spice-devel] [RFC PATCH 2/2] Start writing some documentation on protocol

[Frediano Ziglio]

> 
> On Fri, 2016-09-09 at 10:44 +0100, Frediano Ziglio wrote:
> > Signed-off-by: Frediano Ziglio <fziglio at redhat.com>
> > ---
> >  docs/spice_protocol.txt | 48
> > ++++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 48 insertions(+)
> > 
> > diff --git a/docs/spice_protocol.txt b/docs/spice_protocol.txt
> > index b62da25..b0ba568 100644
> > --- a/docs/spice_protocol.txt
> > +++ b/docs/spice_protocol.txt
> > @@ -1,2 +1,50 @@
> >  Spice protocol format file
> >  ==========================
> > +
> > +Copyright (C) 2016 Red Hat, Inc.
> > +Licensed under a Creative Commons Attribution-Share Alike 3.0
> > +United States License (see http://creativecommons.org/licenses/by-sa
> > /3.0/us/legalcode).
> > +
> > +Basic
> > +-----
> > +The spice protocol format file defines the network protocol used by
> > spice.
> > +It resemble the C format.
> > +
> > +    file ::= <definitions> <protocol>
> > +    definitions ::= <definition>|<definitions><definition>
> > +    definition ::=
> > <typedef>|<structure>|<enum>|<flags>|<message>|<channel>
> > +    protocol ::= "protocol" <identifier> "{" <protocol_channels> "}"
> > ";"
> > +    protocol_channels ::=
> > <protocol_channel>|<protocol_channels><protocol_channel>
> > +    protocol_channel ::= <identifier> <identifier> [ "=" <integer> ]
> > ";"
> > +    integer ::= <hex>|<dec>
> > +    dec ::= [+-][0-9]+
> > +    hex ::= "0x" [0-9a-f]+
> > +    identifier ::= [a-z][a-z0-9_]*
> > +
> > +(here BNF with some regular expression are used).
> > +
> > +Example:
> > +
> > +    channel ExampleChannel {
> > +       message {
> > +          uint32 dummy;
> > +       } Dummy;
> > +    };
> > +
> > +    protocol Example {
> > +        ExampleChannel first = 1001;
> > +    };
> > +
> > +As you can see brackets like C are used and structures looks like C
> > but you
> > +can also see that keyworks like `channel`, `protocol`, `message` or
> > some
> > +predefined types like `uint32` are proper of the protocol.
> > +
> > +Comments
> > +--------
> > +Both C and C++ style comments are supported
> > +
> > +    // this is a comment
> > +    /* this is a comment too
> > +       but can be split in multiple lines */
> > +
> > +
> 
> 
> I think that documenting the protocol is badly needed, but I fear that
> unless this documentation is connected to the protocol definition in
> some way, it will get out-of-sync pretty quickly.
> 
> Jonathon
> 

out-of-sync can be a problem but it's also true that the sync
cannot move far away as this would break compatibility.
Also we could extend the tests Christophe did to make sure that
syntax is still working the same way.
I was thinking about some small tools to extract documentation from
spice_parser.py and other files but didn't manage to think any good
way in a timely fashion. I wouldn't create another "project"
(spend too much time) writing a tool that generate the documentation
from source, looks like the information we need are quite spread all
over the sources. I also tried to look at pyparsing (not really
familiar with) to get a list the overall syntax documentation but
didn't find nothing either.

Do you think I (I would prefer a WE) should investigate more on
getting documentation from source? I think not, unless someone with
better knowledge came with an easy solution.

Do you think it's worth if I continue this branch/patches or should
I discard them?

Frediano