Python: document VariantFieldDeclaration

[babeltrace.git] / bindings / python / bt.py

diff --git a/bindings/python/bt.py b/bindings/python/bt.py
index 4106b0def28a93cd95f11ad5df94907763041d5d..469a3208d539adb677039efda8dc0d7419ee1ba4 100644 (file)
--- a/bindings/python/bt.py
+++ b/bindings/python/bt.py
@@ -880,7 +880,11 @@ class EventDeclaration:
 
 
 class FieldDeclaration:
-    """Field declaration class. Do not instantiate."""
+    """
+    Base class for concrete field declarations.
+
+    This class is not meant to be instantiated by the user.
+    """
 
     def __init__(self):
         raise NotImplementedError("FieldDeclaration cannot be instantiated")
@@ -892,15 +896,16 @@ class FieldDeclaration:
 
     @property
     def name(self):
-        """Return the name of a FieldDeclaration or None on error."""
+        """
+        Field's name, or ``None`` on error.
+        """
 
         return self._name
 
     @property
     def type(self):
         """
-        Return the FieldDeclaration's type. One of the entries in class
-        CTFTypeId.
+        Field's type (one of :class:`CTFTypeId` constants).
         """
 
         return nbt._bt_ctf_field_type(self._fd)
@@ -908,7 +913,7 @@ class FieldDeclaration:
     @property
     def scope(self):
         """
-        Return the FieldDeclaration's scope.
+        Field's scope (one of :class:`CTFScope` constants).
         """
 
         return self._s
@@ -970,14 +975,22 @@ class IntegerFieldDeclaration(FieldDeclaration):
 
 
 class EnumerationFieldDeclaration(FieldDeclaration):
-    """Do not instantiate."""
+    """
+    Enumeration field declaration.
+
+    .. note::
+
+       As of this version, this class is missing some properties.
+    """
 
     def __init__(self):
         raise NotImplementedError("EnumerationFieldDeclaration cannot be instantiated")
 
 
 class ArrayFieldDeclaration(FieldDeclaration):
-    """Do not instantiate."""
+    """
+    Static array field declaration.
+    """
 
     def __init__(self):
         raise NotImplementedError("ArrayFieldDeclaration cannot be instantiated")
@@ -985,8 +998,8 @@ class ArrayFieldDeclaration(FieldDeclaration):
     @property
     def length(self):
         """
-        Return the length of an array or a negative
-        value on error.
+        Static array's fixed length (number of contained elements), or
+        a negative value on error.
         """
 
         return nbt._bt_ctf_get_array_len(self._fd)
@@ -994,7 +1007,7 @@ class ArrayFieldDeclaration(FieldDeclaration):
     @property
     def element_declaration(self):
         """
-        Return element declaration.
+        Underlying element's field declaration.
         """
 
         field_decl_ptr = nbt._bt_python_get_array_element_declaration(self._fd)
@@ -1003,7 +1016,13 @@ class ArrayFieldDeclaration(FieldDeclaration):
 
 
 class SequenceFieldDeclaration(FieldDeclaration):
-    """Do not instantiate."""
+    """
+    Sequence (dynamic array) field declaration.
+
+    .. note::
+
+       As of this version, this class is missing some properties.
+    """
 
     def __init__(self):
         raise NotImplementedError("SequenceFieldDeclaration cannot be instantiated")
@@ -1011,7 +1030,7 @@ class SequenceFieldDeclaration(FieldDeclaration):
     @property
     def element_declaration(self):
         """
-        Return element declaration.
+        Underlying element's field declaration.
         """
 
         field_decl_ptr = nbt._bt_python_get_sequence_element_declaration(self._fd)
@@ -1020,28 +1039,53 @@ class SequenceFieldDeclaration(FieldDeclaration):
 
 
 class FloatFieldDeclaration(FieldDeclaration):
-    """Do not instantiate."""
+    """
+    Floating point number field declaration.
+
+    .. note::
+
+       As of this version, this class is missing some properties.
+    """
 
     def __init__(self):
         raise NotImplementedError("FloatFieldDeclaration cannot be instantiated")
 
 
 class StructureFieldDeclaration(FieldDeclaration):
-    """Do not instantiate."""
+    """
+    Structure (ordered map of field names to field declarations) field
+    declaration.
+
+    .. note::
+
+       As of this version, this class is missing some properties.
+    """
 
     def __init__(self):
         raise NotImplementedError("StructureFieldDeclaration cannot be instantiated")
 
 
 class StringFieldDeclaration(FieldDeclaration):
-    """Do not instantiate."""
+    """
+    String (NULL-terminated array of bytes) field declaration.
+
+    .. note::
+
+       As of this version, this class is missing some properties.
+    """
 
     def __init__(self):
         raise NotImplementedError("StringFieldDeclaration cannot be instantiated")
 
 
 class VariantFieldDeclaration(FieldDeclaration):
-    """Do not instantiate."""
+    """
+    Variant (dynamic selection between different types) field declaration.
+
+    .. note::
+
+       As of this version, this class is missing some properties.
+    """
 
     def __init__(self):
         raise NotImplementedError("VariantFieldDeclaration cannot be instantiated")