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@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/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 _______________________________________________ Spice-devel mailing list Spice-devel@xxxxxxxxxxxxxxxxxxxxx https://lists.freedesktop.org/mailman/listinfo/spice-devel