diff options
author | Emmanuele Bassi <ebassi@gnome.org> | 2022-10-29 18:09:23 +0100 |
---|---|---|
committer | Emmanuele Bassi <ebassi@gnome.org> | 2023-01-08 14:50:28 +0000 |
commit | e9e3866133275cedcec6b9953adaf88fefcabbf8 (patch) | |
tree | 813abc2433ad2d50c23303a6cc0c7b09a8646a92 /giscanner/annotationparser.py | |
parent | 221b006625f2185b5a4d81d544bd0a2acf70ef60 (diff) | |
download | gobject-introspection-e9e3866133275cedcec6b9953adaf88fefcabbf8.tar.gz |
Add copy and free function annotations for POD types
Plain Old Data (POD) types with or without a representation in the GType
type system can still have a copy and/or a free function. We should
allow annotating these types with their corresponding functions for
copying their data into a new instance, and freeing their data.
From a language bindings perspective, POD types should have a boxed
GType wrapper around them, so they can use the generic GBoxed API to
copy and free instances; from a documentation perspective, though, it'd
be good to have a way to match a structured type, like a struct or a
union, with its copy and free functions.
In order to do that, we add two new header block annotations:
- (copy-func function_name)
- (free-func function_name)
These annotations work exactly like ref-func and unref-func for typed
instances:
/**
* GdkRGBA: (copy-func gdk_rgba_copy)
* (free-func gdk_rgba_free)
* @red: ...
* @green: ...
* @blue: ...
* @alpha: ...
*
* ...
*/
The function is stored in the GIR data as two new attributes for the
`<record>` and `<union>` elements:
<record name="RGBA"
c:type="GdkRGBA"
copy-function="gdk_rgba_copy"
free-function="gdk_rgba_free"
glib:type-name="GdkRGBA"
glib:get-type="gdk_rgba_get_type"
c:symbol-prefix="gdk_rgba">
The annotations are not mandatory.
See: #14
Diffstat (limited to 'giscanner/annotationparser.py')
-rw-r--r-- | giscanner/annotationparser.py | 63 |
1 files changed, 58 insertions, 5 deletions
diff --git a/giscanner/annotationparser.py b/giscanner/annotationparser.py index 3952b24b..e567115a 100644 --- a/giscanner/annotationparser.py +++ b/giscanner/annotationparser.py @@ -193,11 +193,13 @@ ANN_ARRAY = 'array' ANN_ATTRIBUTES = 'attributes' ANN_CLOSURE = 'closure' ANN_CONSTRUCTOR = 'constructor' +ANN_COPY_FUNC = 'copy-func' ANN_DEFAULT_VALUE = 'default-value' ANN_DESTROY = 'destroy' ANN_ELEMENT_TYPE = 'element-type' ANN_EMITTER = 'emitter' ANN_FOREIGN = 'foreign' +ANN_FREE_FUNC = 'free-func' ANN_GET_PROPERTY = 'get-property' ANN_GET_VALUE_FUNC = 'get-value-func' ANN_GETTER = 'getter' @@ -790,6 +792,18 @@ class GtkDocAnnotatable(object): self._validate_annotation(position, ann_name, options, exact_n_options=0) + def _do_validate_copy_func(self, position, ann_name, options): + ''' + Validate the ``(copy-func)`` annotation. + + :param position: :class:`giscanner.message.Position` of the line in the source file + containing the annotation to be validated + :param ann_name: name of the annotation holding the options to validate + :param options: annotation options to validate + ''' + + self._validate_annotation(position, ann_name, options, exact_n_options=1) + def _do_validate_default_value(self, position, ann_name, options): ''' Validate the ``(default-value)`` annotation. @@ -851,6 +865,18 @@ class GtkDocAnnotatable(object): self._validate_annotation(position, ann_name, options, exact_n_options=0) + def _do_validate_free_func(self, position, ann_name, options): + ''' + Validate the ``(free-func)`` annotation. + + :param position: :class:`giscanner.message.Position` of the line in the source file + containing the annotation to be validated + :param ann_name: name of the annotation holding the options to validate + :param options: annotation options to validate + ''' + + self._validate_annotation(position, ann_name, options, exact_n_options=1) + def _do_validate_get_property(self, position, ann_name, options): ''' Validate the ``(get-property)`` annotation. @@ -1127,9 +1153,24 @@ class GtkDocParameter(GtkDocAnnotatable): __slots__ = ('name', 'description') - valid_annotations = (ANN_ALLOW_NONE, ANN_ARRAY, ANN_ATTRIBUTES, ANN_CLOSURE, ANN_DESTROY, - ANN_ELEMENT_TYPE, ANN_IN, ANN_INOUT, ANN_OUT, ANN_SCOPE, ANN_SKIP, - ANN_TRANSFER, ANN_TYPE, ANN_OPTIONAL, ANN_NULLABLE, ANN_NOT) + valid_annotations = ( + ANN_ALLOW_NONE, + ANN_ARRAY, + ANN_ATTRIBUTES, + ANN_CLOSURE, + ANN_DESTROY, + ANN_ELEMENT_TYPE, + ANN_IN, + ANN_INOUT, + ANN_OUT, + ANN_SCOPE, + ANN_SKIP, + ANN_TRANSFER, + ANN_TYPE, + ANN_OPTIONAL, + ANN_NULLABLE, + ANN_NOT, + ) def __init__(self, name, position=None): GtkDocAnnotatable.__init__(self, position) @@ -1151,8 +1192,18 @@ class GtkDocTag(GtkDocAnnotatable): __slots__ = ('name', 'value', 'description') - valid_annotations = (ANN_ALLOW_NONE, ANN_ARRAY, ANN_ATTRIBUTES, ANN_ELEMENT_TYPE, ANN_SKIP, - ANN_TRANSFER, ANN_TYPE, ANN_NULLABLE, ANN_OPTIONAL, ANN_NOT) + valid_annotations = ( + ANN_ALLOW_NONE, + ANN_ARRAY, + ANN_ATTRIBUTES, + ANN_ELEMENT_TYPE, + ANN_SKIP, + ANN_TRANSFER, + ANN_TYPE, + ANN_NULLABLE, + ANN_OPTIONAL, + ANN_NOT, + ) def __init__(self, name, position=None): GtkDocAnnotatable.__init__(self, position) @@ -1182,9 +1233,11 @@ class GtkDocCommentBlock(GtkDocAnnotatable): valid_annotations = ( ANN_ATTRIBUTES, ANN_CONSTRUCTOR, + ANN_COPY_FUNC, ANN_DEFAULT_VALUE, ANN_EMITTER, ANN_FOREIGN, + ANN_FREE_FUNC, ANN_GET_PROPERTY, ANN_GET_VALUE_FUNC, ANN_GETTER, |