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

[Jonathon Jongsma]

On Thu, 2016-09-15 at 07:08 -0400, Frediano Ziglio wrote:
> > 
> > 
> > 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/b
> > > y-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.

No, at the moment I think it's probably not worth spending time on a
new tool to extract documentation. 

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

I don't think they need to be discarded.

Jonathon