Re: [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 
> > > ---
> > >  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 ::= |
> > > +definition ::=
> > > |
> > > +protocol ::= "protocol"  "{" 
> > > "}"
> > > ";"
> > > +protocol_channels ::=
> > > |
> > > +protocol_channel ::=   [ "="
> > >  ]
> > > ";"
> > > +integer ::= |
> > > +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@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/spice-devel

Re: [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 
> > ---
> >  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 ::= |
> > +definition ::=
> > |
> > +protocol ::= "protocol"  "{"  "}"
> > ";"
> > +protocol_channels ::=
> > |
> > +protocol_channel ::=   [ "="  ]
> > ";"
> > +integer ::= |
> > +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@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/spice-devel

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

[Jonathon Jongsma]

On Fri, 2016-09-09 at 10:44 +0100, Frediano Ziglio wrote:
> Signed-off-by: Frediano Ziglio 
> ---
>  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 ::= |
> +definition ::=
> |
> +protocol ::= "protocol"  "{"  "}"
> ";"
> +protocol_channels ::=
> |
> +protocol_channel ::=   [ "="  ]
> ";"
> +integer ::= |
> +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
___
Spice-devel mailing list
Spice-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/spice-devel

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

[Frediano Ziglio]

Signed-off-by: Frediano Ziglio 
---
 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 ::= |
+definition ::= |
+protocol ::= "protocol"  "{"  "}" ";"
+protocol_channels ::= 
|
+protocol_channel ::=   [ "="  ] ";"
+integer ::= |
+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 */
+
+
-- 
2.7.4

___
Spice-devel mailing list
Spice-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/spice-devel