> > On Fri, 2016-09-09 at 10:44 +0100, Frediano Ziglio wrote: > > Signed-off-by: Frediano Ziglio <fziglio@xxxxxxxxxx> > > --- > > 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 _______________________________________________ Spice-devel mailing list Spice-devel@xxxxxxxxxxxxxxxxxxxxx https://lists.freedesktop.org/mailman/listinfo/spice-devel