From 62d7eb34260b2b7059fc100747a6d8f95f8d44cf Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Tue, 9 Dec 2014 21:58:26 -0500 Subject: [PATCH] Python: document writer.VariantFieldDeclaration MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Philippe Proulx Signed-off-by: Jérémie Galarneau --- bindings/python/writer.py | 46 +++++++++++++++++++++++++++++++++------ 1 file changed, 39 insertions(+), 7 deletions(-) diff --git a/bindings/python/writer.py b/bindings/python/writer.py index 9bf9e688..4841aa1c 100644 --- a/bindings/python/writer.py +++ b/bindings/python/writer.py @@ -823,9 +823,23 @@ class StructureFieldDeclaration(FieldDeclaration): class VariantFieldDeclaration(FieldDeclaration): + """ + Variant field declaration. + + A CTF variant is a dynamic selection between different fields. + The value of a *tag* (a CTF enumeration) determines what is the + current selected field. All the possible fields must be added to + its field declaration before using an actual variant field. + """ + def __init__(self, enum_tag, tag_name): """ - Create a new variant field declaration. + Creates an empty variant field declaration with tag field + declaration *enum_tag* (instance of + :class:`EnumerationFieldDeclaration`) named *tag_name* + (string). + + :exc:`ValueError` is raised on error. """ isinst = isinstance(enum_tag, EnumerationFieldDeclaration) @@ -839,7 +853,9 @@ class VariantFieldDeclaration(FieldDeclaration): @property def tag_name(self): """ - Get the variant's tag name. + Variant field declaration tag name. + + :exc:`TypeError` is raised on error. """ ret = nbt._bt_ctf_field_type_variant_get_tag_name(self._ft) @@ -852,7 +868,10 @@ class VariantFieldDeclaration(FieldDeclaration): @property def tag_type(self): """ - Get the variant's tag type. + Variant field declaration tag field declaration + (:class:`EnumerationFieldDeclaration` object). + + :exc:`TypeError` is raised on error. """ ret = nbt._bt_ctf_field_type_variant_get_tag_type(self._ft) @@ -864,7 +883,11 @@ class VariantFieldDeclaration(FieldDeclaration): def add_field(self, field_type, field_name): """ - Add a field of type "field_type" to the variant. + Registers the :class:`FieldDeclaration` object *field_type* + as the variant's selected type when the variant's tag's current + label is *field_name*. + + :exc:`ValueError` is raised on error. """ ret = nbt._bt_ctf_field_type_variant_add_field(self._ft, @@ -877,7 +900,10 @@ class VariantFieldDeclaration(FieldDeclaration): @property def fields(self): """ - Generator returning the variant's field as tuples of (field name, field declaration). + Generates the (field name, :class:`FieldDeclaration`) pairs + of this variant field declaration. + + :exc:`TypeError` is raised on error. """ count = nbt._bt_ctf_field_type_variant_get_field_count(self._ft) @@ -903,7 +929,10 @@ class VariantFieldDeclaration(FieldDeclaration): def get_field_by_name(self, name): """ - Get a field declaration by name (FieldDeclaration). + Returns the :class:`FieldDeclaration` selected when the + variant's tag's current label is *name*. + + :exc:`TypeError` is raised on error. """ field_type_native = nbt._bt_ctf_field_type_variant_get_field_type_by_name(self._ft, @@ -917,7 +946,10 @@ class VariantFieldDeclaration(FieldDeclaration): def get_field_from_tag(self, tag): """ - Get a field declaration from tag (EnumerationField). + Returns the :class:`FieldDeclaration` selected by the current + label of the :class:`EnumerationField` *tag*. + + :exc:`TypeError` is raised on error. """ field_type_native = nbt._bt_ctf_field_type_variant_get_field_type_from_tag(self._ft, tag._f) -- 2.34.1