fdo-mirrors/xorg-xcbproto
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/xorg/proto/xcbproto.git synced 2026-05-05 21:38:02 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

xproto: add doc tags, xcbgen: handle doc tags

Browse source 
Signed-off-by: Julien Danjou <julien@danjou.info>
This commit is contained in:
Michael Stapelberg 2011-11-27 10:35:06 +00:00 • committed by Julien Danjou
parent 8c41b3c901
commit b02b7f8dcf
5 changed files with 2950 additions and 20 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

35
doc/xml-xcb.txt
View file

@ -284,3 +284,38 @@ Expressions
This element represents the number of bits set in the expression.
Documentation
-------------
Documentation for each request, reply or event is stored in the appropriate
element using a <doc> element. The <doc> element can contain the following
elements:
<brief>brief description</brief>
A short description of the request, reply or event. For example "makes a
window visible" for MapWindow. This will end up in the manpage NAME section
and in the doxygen @brief description.
<description><![CDATA[longer description]]></description>
The full description. Use `` to highlight words, such as "Draws
`points_len`-1 lines between each pair of points…"
<example><![CDATA[example code]]</description>
Example C code illustrating the usage of the particular request, reply or
event.
<field name="name">field description</field>
The full description for the specified field. Depending on the context, this
is either a request parameter or a reply/event datastructure field.
<error type="type">error description</field>
The full description for an error which can occur due to this request.
<see type="request" name="name" />
A reference to another relevant program, function, request or event.

63
src/xcb.xsd
View file

@ -201,7 +201,9 @@ authorization from the authors.
<!-- Type for a packet structure -->
<xsd:complexType name="packet-struct">
<xsd:group ref="fields" minOccurs="0" maxOccurs="unbounded" />
<xsd:sequence>
<xsd:group ref="fields" minOccurs="0" maxOccurs="unbounded" />
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string" use="required" />
<xsd:attribute name="number" type="xsd:integer" use="required" />
</xsd:complexType>
@ -225,6 +227,59 @@ authorization from the authors.
<xsd:union memberTypes="xsd:integer hex-integer" />
</xsd:simpleType>
<!-- Type for documentation -->
<xsd:group name="doc-fields">
<xsd:sequence>
<xsd:element name="field">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:attribute name="name" type="xsd:string" />
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:group>
<xsd:group name="error-fields">
<xsd:sequence>
<xsd:element name="error">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:attribute name="type" type="xsd:string" />
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:group>
<xsd:group name="see-fields">
<xsd:sequence>
<xsd:element name="see">
<xsd:complexType>
<xsd:attribute name="name" type="xsd:string" />
<xsd:attribute name="type" type="xsd:string" />
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:group>
<xsd:element name="doc">
<xsd:complexType mixed="true">
<xsd:sequence>
<xsd:element name="brief" type="xsd:string" minOccurs="0" maxOccurs="1" />
<xsd:element name="description" type="xsd:string" minOccurs="0" maxOccurs="1" />
<xsd:element name="example" type="xsd:string" minOccurs="0" maxOccurs="1" />
<xsd:group ref="doc-fields" minOccurs="0" maxOccurs="unbounded" />
<xsd:group ref="error-fields" minOccurs="0" maxOccurs="unbounded" />
<xsd:group ref="see-fields" minOccurs="0" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:group name="macro">
<xsd:choice>
<xsd:element name="request">
@ -248,9 +303,11 @@ authorization from the authors.
<xsd:choice minOccurs="0" maxOccurs="1">
<xsd:element ref="switch" />
</xsd:choice>
<xsd:element ref="doc" minOccurs="0" maxOccurs="1" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element ref="doc" minOccurs="0" maxOccurs="1" />
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string" use="required" />
<xsd:attribute name="opcode" type="xsd:integer" use="required" />
@ -262,6 +319,9 @@ authorization from the authors.
<xsd:complexType>
<xsd:complexContent>
<xsd:extension base="packet-struct">
<xsd:sequence>
<xsd:element ref="doc" minOccurs="0" maxOccurs="1" />
</xsd:sequence>
<xsd:attribute name="no-sequence-number" type="xsd:boolean"
use="optional" />
</xsd:extension>
@ -296,6 +356,7 @@ authorization from the authors.
<xsd:attribute name="name" type="xsd:string" use="required" />
</xsd:complexType>
</xsd:element>
<xsd:element ref="doc" minOccurs="0" maxOccurs="1" />
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string" use="required" />
</xsd:complexType>

2796
src/xproto.xml
View file

File diff suppressed because it is too large Load diff

4
xcbgen/expr.py
View file

@ -11,11 +11,13 @@ class Field(object):
visible is true iff the field should be in the request API.
wire is true iff the field should be in the request structure.
auto is true iff the field is on the wire but not in the request API (e.g. opcode)
enum is the enum name this field refers to, if any.
'''
def __init__(self, type, field_type, field_name, visible, wire, auto):
def __init__(self, type, field_type, field_name, visible, wire, auto, enum=None):
self.type = type
self.field_type = field_type
self.field_name = field_name
self.enum = enum
self.visible = visible
self.wire = wire
self.auto = auto

72
xcbgen/xtypes.py
View file

@ -56,7 +56,7 @@ class Type(object):
'''
raise Exception('abstract fixed_size method not overridden!')
def make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto):
def make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto, enum=None):
'''
Default method for making a data type a member of a structure.
Extend this if the data type needs to add an additional length field or something.
@ -65,7 +65,7 @@ class Type(object):
complex_type is the structure object.
see Field for the meaning of the other parameters.
'''
new_field = Field(self, field_type, field_name, visible, wire, auto)
new_field = Field(self, field_type, field_name, visible, wire, auto, enum)
# We dump the _placeholder_byte if any fields are added.
for (idx, field) in enumerate(complex_type.fields):
@ -123,7 +123,11 @@ class Enum(SimpleType):
SimpleType.__init__(self, name, 4)
self.values = []
self.bits = []
self.doc = None
for item in list(elt):
if item.tag == 'doc':
self.doc = Doc(name, item)
# First check if we're using a default value
if len(list(item)) == 0:
self.values.append((item.get('name'), ''))
@ -170,7 +174,7 @@ class ListType(Type):
self.size = member.size if member.fixed_size() else None
self.nmemb = self.expr.nmemb if self.expr.fixed_size() else None
def make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto):
def make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto, enum=None):
if not self.fixed_size():
# We need a length field.
# Ask our Expression object for it's name, type, and whether it's on the wire.
@ -189,10 +193,10 @@ class ListType(Type):
if needlen:
type = module.get_type(lenfid)
lenfield_type = module.get_type_name(lenfid)
type.make_member_of(module, complex_type, lenfield_type, lenfield_name, True, lenwire, False)
type.make_member_of(module, complex_type, lenfield_type, lenfield_name, True, lenwire, False, enum)
# Add ourself to the structure by calling our original method.
Type.make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto)
Type.make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto, enum)
def resolve(self, module):
if self.resolved:
@ -278,6 +282,7 @@ class ComplexType(Type):
if self.resolved:
return
pads = 0
enum = None
# Resolve all of our field datatypes.
for child in list(self.elt):
@ -289,6 +294,7 @@ class ComplexType(Type):
visible = False
elif child.tag == 'field':
field_name = child.get('name')
enum = child.get('enum')
fkey = child.get('type')
type = module.get_type(fkey)
visible = True
@ -323,7 +329,7 @@ class ComplexType(Type):
# Get the full type name for the field
field_type = module.get_type_name(fkey)
# Add the field to ourself
type.make_member_of(module, self, field_type, field_name, visible, True, False)
type.make_member_of(module, self, field_type, field_name, visible, True, False, enum)
# Recursively resolve the type (could be another structure, list)
type.resolve(module)
@ -413,7 +419,7 @@ class SwitchType(ComplexType):
self.calc_size() # Figure out how big we are
self.resolved = True
def make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto):
def make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto, enum=None):
if not self.fixed_size():
# We need a length field.
# Ask our Expression object for it's name, type, and whether it's on the wire.
@ -432,10 +438,10 @@ class SwitchType(ComplexType):
if needlen:
type = module.get_type(lenfid)
lenfield_type = module.get_type_name(lenfid)
type.make_member_of(module, complex_type, lenfield_type, lenfield_name, True, lenwire, False)
type.make_member_of(module, complex_type, lenfield_type, lenfield_name, True, lenwire, False, enum)
# Add ourself to the structure by calling our original method.
Type.make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto)
Type.make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto, enum)
# size for switch can only be calculated at runtime
def calc_size(self):
@ -483,7 +489,7 @@ class BitcaseType(ComplexType):
self.parents = list(parent)
self.is_bitcase = True
def make_member_of(self, module, switch_type, field_type, field_name, visible, wire, auto):
def make_member_of(self, module, switch_type, field_type, field_name, visible, wire, auto, enum=None):
'''
register BitcaseType with the corresponding SwitchType
@ -491,7 +497,7 @@ class BitcaseType(ComplexType):
complex_type is the structure object.
see Field for the meaning of the other parameters.
'''
new_field = Field(self, field_type, field_name, visible, wire, auto)
new_field = Field(self, field_type, field_name, visible, wire, auto, enum)
# We dump the _placeholder_byte if any bitcases are added.
for (idx, field) in enumerate(switch_type.bitcases):
@ -518,6 +524,11 @@ class Reply(ComplexType):
def __init__(self, name, elt):
ComplexType.__init__(self, name, elt)
self.is_reply = True
self.doc = None
for child in list(elt):
if child.tag == 'doc':
self.doc = Doc(name, child)
def resolve(self, module):
if self.resolved:
@ -541,11 +552,14 @@ class Request(ComplexType):
def __init__(self, name, elt):
ComplexType.__init__(self, name, elt)
self.reply = None
self.doc = None
self.opcode = elt.get('opcode')
for child in list(elt):
if child.tag == 'reply':
self.reply = Reply(name, child)
if child.tag == 'doc':
self.doc = Doc(name, child)
def resolve(self, module):
if self.resolved:
@ -581,6 +595,11 @@ class Event(ComplexType):
tmp = elt.get('no-sequence-number')
self.has_seq = (tmp == None or tmp.lower() == 'false' or tmp == '0')
self.doc = None
for item in list(elt):
if item.tag == 'doc':
self.doc = Doc(name, item)
def add_opcode(self, opcode, name, main):
self.opcodes[name] = opcode
@ -629,4 +648,35 @@ class Error(ComplexType):
out = __main__.output['error']
class Doc(object):
'''
Class representing a <doc> tag.
'''
def __init__(self, name, elt):
self.name = name
self.description = None
self.brief = 'BRIEF DESCRIPTION MISSING'
self.fields = {}
self.errors = {}
self.see = {}
self.example = None
for child in list(elt):
text = child.text if child.text else ''
if child.tag == 'description':
self.description = text.strip()
if child.tag == 'brief':
self.brief = text.strip()
if child.tag == 'field':
self.fields[child.get('name')] = text.strip()
if child.tag == 'error':
self.errors[child.get('type')] = text.strip()
if child.tag == 'see':
self.see[child.get('name')] = child.get('type')
if child.tag == 'example':
self.example = text.strip()
_placeholder_byte = Field(PadType(None), tcard8.name, 'pad0', False, True, False)