diff options
| -rw-r--r-- | ChangeLog | 12 | ||||
| -rw-r--r-- | giscanner/annotationparser.py | 74 | ||||
| -rw-r--r-- | giscanner/ast.py | 11 | ||||
| -rw-r--r-- | giscanner/girwriter.py | 24 | ||||
| -rw-r--r-- | giscanner/glibast.py | 3 | ||||
| -rw-r--r-- | tests/scanner/annotation-1.0-expected.gir | 215 | ||||
| -rw-r--r-- | tests/scanner/annotation.h | 14 | ||||
| -rw-r--r-- | tests/scanner/foo-1.0-expected.gir | 5 |
8 files changed, 282 insertions, 76 deletions
@@ -1,5 +1,17 @@ 2009-01-13 Johan Dahlin <jdahlin@async.com.br> + Bug 555036 – put gtk-doc in GIR + + * giscanner/annotationparser.py: + * giscanner/ast.py: + * giscanner/girwriter.py: + * giscanner/glibast.py: + * tests/scanner/annotation-1.0-expected.gir: + * tests/scanner/annotation.h: + * tests/scanner/foo-1.0-expected.gir: + +2009-01-13 Johan Dahlin <jdahlin@async.com.br> + * giscanner/cachestore.py (CacheStore.load): Catch AttributeError which seems to be occasionally raised for Record. diff --git a/giscanner/annotationparser.py b/giscanner/annotationparser.py index 0e65ada8..3a628f87 100644 --- a/giscanner/annotationparser.py +++ b/giscanner/annotationparser.py @@ -20,8 +20,9 @@ # AnnotationParser - parses gtk-doc annotations -from .ast import (Array, Callback, Class, Enum, Field, Function, Interface, - List, Map, Parameter, Record, Return, Type, Union, Varargs, +from .ast import (Array, Bitfield, Callback, Class, Enum, Field, Function, + Interface, List, Map, Parameter, Record, Return, Type, Union, + Varargs, default_array_types, BASIC_GIR_TYPES, PARAM_DIRECTION_INOUT, @@ -71,6 +72,7 @@ class DocBlock(object): self.name = name self.value = None self.tags = odict() + self.comment = None def __repr__(self): return '<DocBlock %r>' % (self.name, ) @@ -91,6 +93,7 @@ class DocTag(object): def __init__(self, name): self.name = name self.options = [] + self.comment = None class Option(object): @@ -164,34 +167,36 @@ class AnnotationParser(object): if not block_name.endswith(':'): return block = DocBlock(block_name[:-1]) - content = comment[pos+1:] - for line in content.split('\n'): + comment_lines = [] + for line in comment[pos+1:].split('\n'): line = line.lstrip() line = line[2:].strip() # Skip ' *' if not line: continue - if line.startswith('@'): line = line[1:] elif not ': ' in line: + comment_lines.append(line) continue tag = self._parse_tag(line) block.tags[tag.name] = tag - + block.comment = '\n'.join(comment_lines) self._blocks[block.name] = block - def _parse_tag(self, value): + def _parse_tag(self, raw): # Tag: bar # Tag: bar opt1 opt2 - parts = value.split(': ', 1) + parts = raw.split(': ', 1) if len(parts) == 1: tag_name = parts[0] - options = '' + value = '' else: - tag_name, options = parts + tag_name, value = parts + options, rest = self._parse_options(value) tag = DocTag(tag_name) - tag.value = options - tag.options = self._parse_options(options) + tag.value = value + tag.options = options + tag.comment = rest return tag def _parse_options(self, value): @@ -199,6 +204,7 @@ class AnnotationParser(object): # (bar opt1 opt2...) opened = -1 options = {} + last = None for i, c in enumerate(value): if c == '(' and opened == -1: opened = i+1 @@ -215,8 +221,14 @@ class AnnotationParser(object): if option is not None: option = Option(option) options[name] = option + last = i + 2 opened = -1 - return options + + if last is not None: + rest = value[last:].strip() + else: + rest = None + return options, rest class AnnotationApplier(object): @@ -242,6 +254,8 @@ class AnnotationApplier(object): self._parse_function(node) elif isinstance(node, Enum): self._parse_enum(node) + elif isinstance(node, Bitfield): + self._parse_bitfield(node) elif isinstance(node, Class): self._parse_class(node) elif isinstance(node, Interface): @@ -256,7 +270,7 @@ class AnnotationApplier(object): self._parse_boxed(node) def _parse_class(self, class_): - block = self._blocks.get(class_.name) + block = self._blocks.get(class_.type_name) self._parse_version(class_, block) self._parse_constructors(class_.constructors) self._parse_methods(class_.methods) @@ -264,14 +278,18 @@ class AnnotationApplier(object): self._parse_properties(class_, class_.properties) self._parse_signals(class_, class_.signals) self._parse_fields(class_, class_.fields) + if block: + class_.doc = block.comment def _parse_interface(self, interface): - block = self._blocks.get(interface.name) + block = self._blocks.get(interface.type_name) self._parse_version(interface, block) self._parse_methods(interface.methods) self._parse_properties(interface, interface.properties) self._parse_signals(interface, interface.signals) self._parse_fields(interface, interface.fields) + if block: + interface.doc = block.comment def _parse_record(self, record): block = self._blocks.get(record.symbol) @@ -280,12 +298,16 @@ class AnnotationApplier(object): self._parse_fields(record, record.fields) if isinstance(record, GLibBoxed): self._parse_methods(record.methods) + if block: + record.doc = block.comment def _parse_boxed(self, boxed): block = self._blocks.get(boxed.name) self._parse_version(boxed, block) self._parse_constructors(boxed.constructors) self._parse_methods(boxed.methods) + if block: + boxed.doc = block.comment def _parse_union(self, union): block = self._blocks.get(union.name) @@ -293,10 +315,20 @@ class AnnotationApplier(object): self._parse_constructors(union.constructors) if isinstance(union, GLibBoxed): self._parse_methods(union.methods) + if block: + union.doc = block.comment def _parse_enum(self, enum): block = self._blocks.get(enum.symbol) self._parse_version(enum, block) + if block: + enum.doc = block.comment + + def _parse_bitfield(self, bitfield): + block = self._blocks.get(bitfield.symbol) + self._parse_version(bitfield, block) + if block: + bitfield.doc = block.comment def _parse_constructors(self, constructors): for ctor in constructors: @@ -322,12 +354,16 @@ class AnnotationApplier(object): block = self._blocks.get('%s:%s' % (parent.type_name, prop.name)) self._parse_version(prop, block) self._parse_deprecated(prop, block) + if block: + prop.doc = block.comment def _parse_callback(self, callback): block = self._blocks.get(callback.ctype) self._parse_version(callback, block) self._parse_params(callback, callback.parameters, block) self._parse_return(callback, callback.retval, block) + if block: + callback.doc = block.comment def _parse_function(self, func): block = self._blocks.get(func.symbol) @@ -335,6 +371,8 @@ class AnnotationApplier(object): self._parse_deprecated(func, block) self._parse_params(func, func.parameters, block) self._parse_return(func, func.retval, block) + if block: + func.doc = block.comment def _parse_signal(self, parent, signal): block = self._blocks.get('%s::%s' % (parent.type_name, signal.name)) @@ -359,6 +397,8 @@ class AnnotationApplier(object): tag = None self._parse_param(signal, param, tag) self._parse_return(signal, signal.retval, block) + if block: + signal.doc = block.comment def _parse_field(self, parent, field): if isinstance(field, Callback): @@ -373,6 +413,8 @@ class AnnotationApplier(object): tag = self._get_tag(block, TAG_RETURNS) options = getattr(tag, 'options', {}) self._parse_param_ret_common(parent, return_, options) + if tag is not None and tag.comment is not None: + return_.doc = tag.comment def _parse_param(self, parent, param, tag): options = getattr(tag, 'options', {}) @@ -383,6 +425,8 @@ class AnnotationApplier(object): param.scope = scope.one() param.transfer = PARAM_TRANSFER_NONE self._parse_param_ret_common(parent, param, options) + if tag is not None and tag.comment is not None: + param.doc = tag.comment def _parse_param_ret_common(self, parent, node, options): node.direction = self._extract_direction(node, options) diff --git a/giscanner/ast.py b/giscanner/ast.py index b141691d..b3c1fff5 100644 --- a/giscanner/ast.py +++ b/giscanner/ast.py @@ -201,6 +201,7 @@ class Function(Node): self.symbol = symbol self.throws = not not throws self.is_method = False + self.doc = None def get_parameter_index(self, name): for i, parameter in enumerate(self.parameters): @@ -312,6 +313,7 @@ class Parameter(TypeContainer): self.scope = scope self.closure_index = -1 self.destroy_index = -1 + self.doc = None def __repr__(self): return 'Parameter(%r, %r)' % (self.name, self.type) @@ -323,6 +325,7 @@ class Enum(Node): Node.__init__(self, name) self.symbol = symbol self.members = members + self.doc = None def __repr__(self): return 'Enum(%r, %r)' % (self.name, self.members) @@ -334,6 +337,7 @@ class Bitfield(Node): Node.__init__(self, name) self.symbol = symbol self.members = members + self.doc = None def __repr__(self): return 'Bitfield(%r, %r)' % (self.name, self.members) @@ -358,6 +362,7 @@ class Record(Node): self.constructors = [] self.symbol = symbol self.disguised = disguised + self.doc = None # BW compat, remove Struct = Record @@ -385,6 +390,7 @@ class Return(TypeContainer): def __init__(self, rtype, transfer=None): TypeContainer.__init__(self, None, rtype, transfer) self.direction = PARAM_DIRECTION_OUT + self.doc = None def __repr__(self): return 'Return(%r)' % (self.type, ) @@ -403,6 +409,7 @@ class Class(Node): self.constructors = [] self.properties = [] self.fields = [] + self.doc = None def __repr__(self): return '%s(%r, %r, %r)' % ( @@ -419,6 +426,7 @@ class Interface(Node): self.properties = [] self.fields = [] self.prerequisites = [] + self.doc = None def __repr__(self): return '%s(%r, %r)' % ( @@ -448,6 +456,7 @@ class Property(Node): self.writable = writable self.construct = construct self.construct_only = construct_only + self.doc = None def __repr__(self): return '%s(%r, %r)' % ( @@ -466,6 +475,7 @@ class Callback(Node): self.parameters = parameters self.ctype = ctype self.throws = False + self.doc = None def __repr__(self): return 'Callback(%r, %r, %r)' % ( @@ -479,6 +489,7 @@ class Union(Node): self.fields = [] self.constructors = [] self.symbol = symbol + self.doc = None def __repr__(self): return 'Union(%r, %r)' % (self.name, self.fields, ) diff --git a/giscanner/girwriter.py b/giscanner/girwriter.py index e72b0289..a5d1637a 100644 --- a/giscanner/girwriter.py +++ b/giscanner/girwriter.py @@ -119,6 +119,8 @@ class GIRWriter(XMLWriter): def _write_function(self, func, tag_name='function'): attrs = [('name', func.name), ('c:identifier', func.symbol)] + if func.doc: + attrs.append(('doc', func.doc)) self._append_version(func, attrs) self._append_deprecated(func, attrs) self._append_throws(func, attrs) @@ -143,6 +145,8 @@ class GIRWriter(XMLWriter): attrs = [] attrs.append(('transfer-ownership', return_.transfer)) + if return_.doc: + attrs.append(('doc', return_.doc)) with self.tagcontext('return-value', attrs): self._write_type(return_.type) @@ -171,6 +175,8 @@ class GIRWriter(XMLWriter): attrs.append(('closure', '%d' % parameter.closure_index)) if parameter.destroy_index >= 0: attrs.append(('destroy', '%d' % parameter.destroy_index)) + if parameter.doc: + attrs.append(('doc', parameter.doc)) with self.tagcontext('parameter', attrs): self._write_type(parameter.type) @@ -222,6 +228,8 @@ class GIRWriter(XMLWriter): def _write_enum(self, enum): attrs = [('name', enum.name)] + if enum.doc: + attrs.append(('doc', enum.doc)) self._append_version(enum, attrs) self._append_deprecated(enum, attrs) if isinstance(enum, GLibEnum): @@ -236,6 +244,8 @@ class GIRWriter(XMLWriter): def _write_bitfield(self, bitfield): attrs = [('name', bitfield.name)] + if bitfield.doc: + attrs.append(('doc', bitfield.doc)) self._append_version(bitfield, attrs) self._append_deprecated(bitfield, attrs) if isinstance(bitfield, GLibFlags): @@ -265,6 +275,8 @@ class GIRWriter(XMLWriter): def _write_class(self, node): attrs = [('name', node.name), ('c:type', node.ctype)] + if node.doc: + attrs.append(('doc', node.doc)) self._append_version(node, attrs) self._append_deprecated(node, attrs) if isinstance(node, Class): @@ -303,6 +315,8 @@ class GIRWriter(XMLWriter): def _write_boxed(self, boxed): attrs = [('c:type', boxed.ctype), ('glib:name', boxed.name)] + if boxed.doc: + attrs.append(('doc', boxed.doc)) attrs.extend(self._boxed_attrs(boxed)) with self.tagcontext('glib:boxed', attrs): self._write_boxed_ctors_methods(boxed) @@ -320,12 +334,16 @@ class GIRWriter(XMLWriter): attrs.append(('construct', '1')) if prop.construct_only: attrs.append(('construct-only', '1')) + if prop.doc: + attrs.append(('doc', prop.doc)) with self.tagcontext('property', attrs): self._write_type(prop.type) def _write_callback(self, callback): # FIXME: reuse _write_function attrs = [('name', callback.name), ('c:type', callback.ctype)] + if callback.doc: + attrs.append(('doc', callback.doc)) self._append_version(callback, attrs) self._append_deprecated(callback, attrs) self._append_throws(callback, attrs) @@ -348,6 +366,8 @@ class GIRWriter(XMLWriter): ('c:type', record.symbol)] if record.disguised: attrs.append(('disguised', '1')) + if record.doc: + attrs.append(('doc', record.doc)) self._append_version(record, attrs) self._append_deprecated(record, attrs) if isinstance(record, GLibBoxed): @@ -362,6 +382,8 @@ class GIRWriter(XMLWriter): def _write_union(self, union): attrs = [('name', union.name), ('c:type', union.symbol)] + if union.doc: + attrs.append(('doc', union.doc)) self._append_version(union, attrs) self._append_deprecated(union, attrs) if isinstance(union, GLibBoxed): @@ -396,6 +418,8 @@ class GIRWriter(XMLWriter): def _write_signal(self, signal): attrs = [('name', signal.name)] + if signal.doc: + attrs.append(('doc', signal.doc)) self._append_version(signal, attrs) self._append_deprecated(signal, attrs) with self.tagcontext('glib:signal', attrs): diff --git a/giscanner/glibast.py b/giscanner/glibast.py index a804f620..60f214b7 100644 --- a/giscanner/glibast.py +++ b/giscanner/glibast.py @@ -136,7 +136,7 @@ class GLibBoxedOther(Node, GLibBoxed): Node.__init__(self, name) GLibBoxed.__init__(self, type_name, get_type) self.ctype = type_name - + self.doc = None class GLibInterface(Interface): @@ -159,3 +159,4 @@ class GLibSignal(Node): Node.__init__(self, name) self.retval = retval self.parameters = [] + self.doc = None diff --git a/tests/scanner/annotation-1.0-expected.gir b/tests/scanner/annotation-1.0-expected.gir index 71d77dc3..638d7cfd 100644 --- a/tests/scanner/annotation-1.0-expected.gir +++ b/tests/scanner/annotation-1.0-expected.gir @@ -7,24 +7,28 @@ <include name="GObject" version="2.0"/> <include name="utility" version="1.0"/> <namespace name="annotation" version="1.0" shared-library="annotation"> - <callback name="Callback" c:type="AnnotationCallback"> - <return-value transfer-ownership="none"> + <callback name="Callback" + c:type="AnnotationCallback" + doc="This is a callback."> + <return-value transfer-ownership="none" doc="array of ints"> <type name="int" c:type="gint*"/> </return-value> <parameters> - <parameter name="in" transfer-ownership="none"> + <parameter name="in" transfer-ownership="none" doc="array of ints"> <type name="int" c:type="gint*"/> </parameter> </parameters> </callback> - <callback name="ListCallback" c:type="AnnotationListCallback"> - <return-value transfer-ownership="container"> + <callback name="ListCallback" + c:type="AnnotationListCallback" + doc="This is a callback taking a list."> + <return-value transfer-ownership="container" doc="list of strings"> <type name="GLib.List" c:type="GList*"> <type name="utf8"/> </type> </return-value> <parameters> - <parameter name="in" transfer-ownership="none"> + <parameter name="in" transfer-ownership="none" doc="list of strings"> <type name="GLib.List" c:type="GList*"> <type name="utf8"/> </type> @@ -33,6 +37,7 @@ </callback> <class name="Object" c:type="AnnotationObject" + doc="This is an object used to test annotations." parent="GObject.Object" glib:type-name="AnnotationObject" glib:get-type="annotation_object_get_type"> @@ -41,19 +46,25 @@ <type name="int" c:type="gint"/> </return-value> </method> - <method name="out" c:identifier="annotation_object_out"> + <method name="out" + c:identifier="annotation_object_out" + doc="This is a test for out arguments"> <return-value transfer-ownership="none"> <type name="int" c:type="gint"/> </return-value> <parameters> - <parameter name="outarg" direction="out" transfer-ownership="full"> + <parameter name="outarg" + direction="out" + transfer-ownership="full" + doc="This is an argument test"> <type name="int" c:type="int*"/> </parameter> </parameters> </method> <method name="create_object" - c:identifier="annotation_object_create_object"> - <return-value transfer-ownership="full"> + c:identifier="annotation_object_create_object" + doc="Test returning a caller-owned object"> + <return-value transfer-ownership="full" doc="The object"> <type name="GObject.Object" c:type="GObject*"/> </return-value> </method> @@ -68,35 +79,44 @@ </parameters> </method> <method name="notrans" c:identifier="annotation_object_notrans"> - <return-value transfer-ownership="none"> + <return-value transfer-ownership="none" + doc="An object, not referenced"> <type name="GObject.Object" c:type="GObject*"/> </return-value> </method> - <method name="inout" c:identifier="annotation_object_inout"> + <method name="inout" + c:identifier="annotation_object_inout" + doc="This is a test for out arguments"> <return-value transfer-ownership="none"> <type name="int" c:type="gint"/> </return-value> <parameters> <parameter name="inoutarg" direction="inout" - transfer-ownership="full"> + transfer-ownership="full" + doc="This is an argument test"> <type name="int" c:type="int*"/> </parameter> </parameters> </method> - <method name="inout2" c:identifier="annotation_object_inout2"> + <method name="inout2" + c:identifier="annotation_object_inout2" + doc="This is a second test for out arguments"> <return-value transfer-ownership="none"> <type name="int" c:type="gint"/> </return-value> <parameters> <parameter name="inoutarg" direction="inout" - transfer-ownership="full"> + transfer-ownership="full" + doc="This is an argument test"> <type name="int" c:type="int*"/> </parameter> </parameters> </method> - <method name="inout3" c:identifier="annotation_object_inout3"> + <method name="inout3" + c:identifier="annotation_object_inout3" + doc="This is a 3th test for out arguments"> <return-value transfer-ownership="none"> <type name="int" c:type="gint"/> </return-value> @@ -104,61 +124,89 @@ <parameter name="inoutarg" direction="inout" transfer-ownership="full" - allow-none="1"> + allow-none="1" + doc="This is an argument test"> <type name="int" c:type="int*"/> </parameter> </parameters> </method> - <method name="in" c:identifier="annotation_object_in"> + <method name="in" + c:identifier="annotation_object_in" + doc="This is a test for in arguments"> <return-value transfer-ownership="none"> <type name="int" c:type="gint"/> </return-value> <parameters> - <parameter name="inarg" transfer-ownership="none"> + <parameter name="inarg" + transfer-ownership="none" + doc="This is an argument test"> <type name="int" c:type="int*"/> </parameter> </parameters> </method> - <method name="calleeowns" c:identifier="annotation_object_calleeowns"> + <method name="calleeowns" + c:identifier="annotation_object_calleeowns" + doc="This is a test for out arguments; GObject defaults to transfer"> <return-value transfer-ownership="none"> <type name="int" c:type="gint"/> </return-value> <parameters> - <parameter name="toown" direction="out" transfer-ownership="full"> + <parameter name="toown" + direction="out" + transfer-ownership="full" + doc="a #GObject"> <type name="GObject.Object" c:type="GObject**"/> </parameter> </parameters> </method> - <method name="calleesowns" c:identifier="annotation_object_calleesowns"> + <method name="calleesowns" + c:identifier="annotation_object_calleesowns" + doc="This is a test for out arguments, one transferred, other not"> <return-value transfer-ownership="none"> <type name="int" c:type="gint"/> </return-value> <parameters> - <parameter name="toown1" direction="out" transfer-ownership="full"> + <parameter name="toown1" + direction="out" + transfer-ownership="full" + doc="a #GObject"> <type name="GObject.Object" c:type="GObject**"/> </parameter> - <parameter name="toown2" direction="out" transfer-ownership="none"> + <parameter name="toown2" + direction="out" + transfer-ownership="none" + doc="a #GObject"> <type name="GObject.Object" c:type="GObject**"/> </parameter> </parameters> </method> - <method name="get_strings" c:identifier="annotation_object_get_strings"> - <return-value transfer-ownership="full"> + <method name="get_strings" + c:identifier="annotation_object_get_strings" + doc="This is a test for returning a list of strings, where +each string needs to be freed."> + <return-value transfer-ownership="full" doc="list of strings"> <type name="GLib.List" c:type="GList*"> <type name="utf8"/> </type> </return-value> </method> - <method name="get_hash" c:identifier="annotation_object_get_hash"> - <return-value transfer-ownership="full"> + <method name="get_hash" + c:identifier="annotation_object_get_hash" + doc="This is a test for returning a hash table mapping strings to +objects."> + <return-value transfer-ownership="full" doc="hash table"> <type name="GLib.HashTable" c:type="GHashTable*"> <type name="utf8"/> <type name="GObject.Object"/> </type> </return-value> </method> - <method name="get_objects" c:identifier="annotation_object_get_objects"> - <return-value transfer-ownership="container"> + <method name="get_objects" + c:identifier="annotation_object_get_objects" + doc="This is a test for returning a list of objects. +The list itself should be freed, but not the internal objects, +intentionally similar example to gtk_container_get_children"> + <return-value transfer-ownership="container" doc="list of objects"> <type name="GLib.SList" c:type="GSList*"> <type name="Object"/> </type> @@ -176,12 +224,16 @@ </parameter> </parameters> </method> - <method name="compute_sum" c:identifier="annotation_object_compute_sum"> + <method name="compute_sum" + c:identifier="annotation_object_compute_sum" + doc="Test taking a zero-terminated array"> <return-value transfer-ownership="none"> <type name="none" c:type="void"/> </return-value> <parameters> - <parameter name="nums" transfer-ownership="none"> + <parameter name="nums" + transfer-ownership="none" + doc="Sequence of numbers"> <array c:type="int*"> <type name="int"/> </array> @@ -189,12 +241,15 @@ </parameters> </method> <method name="compute_sum_n" - c:identifier="annotation_object_compute_sum_n"> + c:identifier="annotation_object_compute_sum_n" + doc="Test taking an array with length parameter"> <return-value transfer-ownership="none"> <type name="none" c:type="void"/> </return-value> <parameters> - <parameter name="nums" transfer-ownership="none"> + <parameter name="nums" + transfer-ownership="none" + doc="Sequence of numbers"> <array zero-terminated="0" length="2" c:type="int*"> <type name="int"/> </array> @@ -205,12 +260,15 @@ </parameters> </method> <method name="compute_sum_nz" - c:identifier="annotation_object_compute_sum_nz"> + c:identifier="annotation_object_compute_sum_nz" + doc="Test taking a zero-terminated array with length parameter"> <return-value transfer-ownership="none"> <type name="none" c:type="void"/> </return-value> <parameters> - <parameter name="nums" transfer-ownership="none"> + <parameter name="nums" + transfer-ownership="none" + doc="Sequence of numbers"> <array length="2" c:type="int*"> <type name="int"/> </array> @@ -220,32 +278,47 @@ </parameter> </parameters> </method> - <method name="parse_args" c:identifier="annotation_object_parse_args"> + <method name="parse_args" + c:identifier="annotation_object_parse_args" + doc="Test taking a zero-terminated array with length parameter"> <return-value transfer-ownership="none"> <type name="none" c:type="void"/> </return-value> <parameters> - <parameter name="argc" direction="inout" transfer-ownership="full"> + <parameter name="argc" + direction="inout" + transfer-ownership="full" + doc="Length of the argument vector"> <type name="int" c:type="int*"/> </parameter> - <parameter name="argv" direction="inout" transfer-ownership="none"> + <parameter name="argv" + direction="inout" + transfer-ownership="none" + doc="Argument vector"> <array length="1" c:type="char***"> <type name="utf8"/> </array> </parameter> </parameters> </method> - <method name="string_out" c:identifier="annotation_object_string_out"> + <method name="string_out" + c:identifier="annotation_object_string_out" + doc="Test returning a string as an out parameter"> <return-value transfer-ownership="none"> <type name="boolean" c:type="gboolean"/> </return-value> <parameters> - <parameter name="str_out" direction="out" transfer-ownership="full"> + <parameter name="str_out" + direction="out" + transfer-ownership="full" + doc="string return value"> <type name="utf8" c:type="char**"/> </parameter> </parameters> </method> - <method name="foreach" c:identifier="annotation_object_foreach"> + <method name="foreach" + c:identifier="annotation_object_foreach" + doc="Test taking a call-scoped callback"> <return-value transfer-ownership="none"> <type name="none" c:type="void"/> </return-value> @@ -253,7 +326,8 @@ <parameter name="func" transfer-ownership="none" scope="call" - closure="2"> + closure="2" + doc="Callback to invoke"> <type name="ForeachFunc" c:type="AnnotationForeachFunc"/> </parameter> <parameter name="user_data" transfer-ownership="none"> @@ -261,12 +335,14 @@ </parameter> </parameters> </method> - <method name="set_data" c:identifier="annotation_object_set_data"> + <method name="set_data" + c:identifier="annotation_object_set_data" + doc="Test taking a guchar * with a length."> <return-value transfer-ownership="none"> <type name="none" c:type="void"/> </return-value> <parameters> - <parameter name="data" transfer-ownership="none"> + <parameter name="data" transfer-ownership="none" doc="The data"> <array length="2" c:type="guchar*"> <type name="uint8"/> </array> @@ -276,12 +352,14 @@ </parameter> </parameters> </method> - <method name="set_data2" c:identifier="annotation_object_set_data2"> + <method name="set_data2" + c:identifier="annotation_object_set_data2" + doc="Test taking a gchar * with a length."> <return-value transfer-ownership="none"> <type name="none" c:type="void"/> </return-value> <parameters> - <parameter name="data" transfer-ownership="none"> + <parameter name="data" transfer-ownership="none" doc="The data"> <array length="2" c:type="gchar*"> <type name="int8"/> </array> @@ -291,12 +369,15 @@ </parameter> </parameters> </method> - <method name="set_data3" c:identifier="annotation_object_set_data3"> + <method name="set_data3" + c:identifier="annotation_object_set_data3" + doc="Test taking a gchar * with a length, overriding the array element +type."> <return-value transfer-ownership="none"> <type name="none" c:type="void"/> </return-value> <parameters> - <parameter name="data" transfer-ownership="none"> + <parameter name="data" transfer-ownership="none" doc="The data"> <array length="2" c:type="gpointer"> <type name="uint8"/> </array> @@ -319,13 +400,16 @@ deprecated="Use better-string-property instead" deprecated-version="1.2" writable="1" - construct="1"> + construct="1" + doc="This is a property which is a string"> <type name="utf8" c:type="gchararray"/> </property> <field name="parent_instance"> <type name="GObject.Object" c:type="GObject"/> </field> <glib:signal name="string-signal" + doc="This is a signal which has a broken signal handler, +it says it's pointer but it's actually a string." version="1.0" deprecated="Use other-signal instead" deprecated-version="1.2"> @@ -333,17 +417,21 @@ <type name="none" c:type="void"/> </return-value> <parameters> - <parameter name="string" transfer-ownership="none"> + <parameter name="string" transfer-ownership="none" doc="a string"> <type name="utf8" c:type="gpointer"/> </parameter> </parameters> </glib:signal> - <glib:signal name="list-signal"> + <glib:signal name="list-signal" + doc="This is a signal which takes a list of strings, but it's not +known by GObject as it's only marked as G_TYPE_POINTER"> <return-value transfer-ownership="full"> <type name="none" c:type="void"/> </return-value> <parameters> - <parameter name="list" transfer-ownership="container"> + <parameter name="list" + transfer-ownership="container" + doc="a list of strings"> <type name="GLib.List" c:type="gpointer"> <type name="utf8"/> </type> @@ -377,10 +465,16 @@ <type name="none" c:type="void"/> </return-value> <parameters> - <parameter name="argc" direction="inout" transfer-ownership="full"> + <parameter name="argc" + direction="inout" + transfer-ownership="full" + doc="The number of args."> <type name="int" c:type="int*"/> </parameter> - <parameter name="argv" direction="inout" transfer-ownership="none"> + <parameter name="argv" + direction="inout" + transfer-ownership="none" + doc="The arguments."> <array length="0" c:type="char***"> <type name="utf8"/> </array> @@ -388,13 +482,16 @@ </parameters> </function> <function name="return_array" c:identifier="annotation_return_array"> - <return-value transfer-ownership="none"> + <return-value transfer-ownership="none" doc="The return value"> <array length="0" c:type="char**"> <type name="utf8"/> </array> </return-value> <parameters> - <parameter name="length" direction="out" transfer-ownership="full"> + <parameter name="length" + direction="out" + transfer-ownership="full" + doc="Number of return values"> <type name="int" c:type="int*"/> </parameter> </parameters> @@ -406,7 +503,9 @@ <type name="none" c:type="void"/> </return-value> </function> - <record name="Struct" c:type="_AnnotationStruct"> + <record name="Struct" + c:type="AnnotationStruct" + doc="This is a test of an array of object in an field of a struct."> <field name="objects" writable="1"> <array zero-terminated="0" c:type="AnnotationObject*" fixed-size="10"> <type name="Object"/> diff --git a/tests/scanner/annotation.h b/tests/scanner/annotation.h index d53cd901..59905134 100644 --- a/tests/scanner/annotation.h +++ b/tests/scanner/annotation.h @@ -7,6 +7,7 @@ * AnnotationCallback: * @in: (in) (transfer none): array of ints * + * This is a callback. * Return value: (transfer none): array of ints */ typedef const gint* (*AnnotationCallback) (const gint *in); @@ -15,10 +16,16 @@ typedef const gint* (*AnnotationCallback) (const gint *in); * AnnotationListCallback: * @in: (in) (transfer none) (element-type utf8): list of strings * + * This is a callback taking a list. * Return value: (transfer container) (element-type utf8): list of strings */ typedef GList* (*AnnotationListCallback) (GList *in); +/** + * AnnotationObject: + * + * This is an object used to test annotations. + */ typedef struct _AnnotationObject AnnotationObject; typedef struct _AnnotationObjectClass AnnotationObjectClass; @@ -100,7 +107,12 @@ void annotation_init (int *argc, char ** annotation_return_array (int *length); void annotation_versioned (void); -struct _AnnotationStruct +/** + * AnnotationStruct: + * + * This is a test of an array of object in an field of a struct. + */ +struct AnnotationStruct { AnnotationObject *objects[10]; }; diff --git a/tests/scanner/foo-1.0-expected.gir b/tests/scanner/foo-1.0-expected.gir index 17fd5200..38872e72 100644 --- a/tests/scanner/foo-1.0-expected.gir +++ b/tests/scanner/foo-1.0-expected.gir @@ -401,7 +401,10 @@ <type name="none" c:type="void"/> </return-value> <parameters> - <parameter name="r1" direction="inout" transfer-ownership="full"> + <parameter name="r1" + direction="inout" + transfer-ownership="full" + doc="add to this rect"> <type name="Rectangle" c:type="FooRectangle*"/> </parameter> <parameter name="r2" transfer-ownership="none"> |