Python: document IntegerFieldDeclaration

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

diff --git a/bindings/python/bt.py b/bindings/python/bt.py
index e79a61bbc9e829b179653a45f80bea1fe26b6289..09cc9d2ff20fc2e5eb9932fafffd148abd8fd5ce 100644 (file)
--- a/bindings/python/bt.py
+++ b/bindings/python/bt.py
@@ -920,7 +920,9 @@ class FieldDeclaration:
 
 
 class IntegerFieldDeclaration(FieldDeclaration):
-    """Do not instantiate."""
+    """
+    Integer field declaration.
+    """
 
     def __init__(self):
         raise NotImplementedError("IntegerFieldDeclaration cannot be instantiated")
@@ -928,22 +930,23 @@ class IntegerFieldDeclaration(FieldDeclaration):
     @property
     def signedness(self):
         """
-        Return the signedness of an integer:
-        0 if unsigned; 1 if signed; -1 on error.
+        0 if this integer is unsigned, 1 if signed, or -1 on error.
         """
 
         return nbt._bt_ctf_get_int_signedness(self._fd)
 
     @property
     def base(self):
-        """Return the base of an int or a negative value on error."""
+        """
+        Integer's base (``int``), or a negative value on error.
+        """
 
         return nbt._bt_ctf_get_int_base(self._fd)
 
     @property
     def byte_order(self):
         """
-        Return the byte order. One of class ByteOrder's entries.
+        Integer's byte order (one of :class:`ByteOrder` constants).
         """
 
         ret = nbt._bt_ctf_get_int_byte_order(self._fd)
@@ -958,8 +961,7 @@ class IntegerFieldDeclaration(FieldDeclaration):
     @property
     def length(self):
         """
-        Return the size, in bits, of an int or a negative
-        value on error.
+        Integer's length in bits, or a negative value on error.
         """
 
         return nbt._bt_ctf_get_int_len(self._fd)
@@ -967,22 +969,30 @@ class IntegerFieldDeclaration(FieldDeclaration):
     @property
     def encoding(self):
         """
-        Return the encoding. One of class CTFStringEncoding's entries.
-        Return a negative value on error.
+        Integer's encoding (one of :class:`CTFStringEncoding`
+        constants).
         """
 
         return nbt._bt_ctf_get_encoding(self._fd)
 
 
 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")
@@ -990,8 +1000,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)
@@ -999,7 +1009,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)
@@ -1008,7 +1018,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")
@@ -1016,7 +1032,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)
@@ -1025,28 +1041,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")