Python: document writer.FloatingPointField

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

diff --git a/bindings/python/writer.py b/bindings/python/writer.py
index e24631d464321acd3f10e9fc8b761c1188d20cdc..62ee2fba3405556fbee31471b645cdb43f4070c6 100644 (file)
--- a/bindings/python/writer.py
+++ b/bindings/python/writer.py
@@ -1064,9 +1064,15 @@ class SequenceFieldDeclaration(FieldDeclaration):
 
 
 class StringFieldDeclaration(FieldDeclaration):
+    """
+    String (NULL-terminated array of bytes) field declaration.
+    """
+
     def __init__(self):
         """
-        Create a new string field declaration.
+        Creates a string field declaration.
+
+        :exc:`ValueError` is raised on error.
         """
 
         self._ft = nbt._bt_ctf_field_type_string_create()
@@ -1075,17 +1081,18 @@ class StringFieldDeclaration(FieldDeclaration):
     @property
     def encoding(self):
         """
-        Get a string declaration's encoding (a constant from the CTFStringEncoding class).
+        String encoding (one of
+        :class:`babeltrace.common.CTFStringEncoding` constants).
+
+        Set this attribute to change this string's encoding.
+
+        :exc:`ValueError` is raised on error.
         """
 
         return nbt._bt_ctf_field_type_string_get_encoding(self._ft)
 
     @encoding.setter
     def encoding(self, encoding):
-        """
-        Set a string declaration's encoding. Must be a constant from the CTFStringEncoding class.
-        """
-
         ret = nbt._bt_ctf_field_type_string_set_encoding(self._ft, encoding)
         if ret < 0:
             raise ValueError("Could not set string encoding.")
@@ -1121,7 +1128,10 @@ def create_field(field_type):
 
 class Field:
     """
-    Base class, do not instantiate.
+    Base class of all fields. This class is not meant to be
+    instantiated by the user, and neither are its subclasses. Use
+    :meth:`Event.payload` to access specific, concrete fields of
+    an event.
     """
 
     def __init__(self, field_type):
@@ -1162,6 +1172,12 @@ class Field:
 
     @property
     def declaration(self):
+        """
+        Field declaration (subclass of :class:`FieldDeclaration`).
+
+        :exc:`TypeError` is raised on error.
+        """
+
         native_field_type = nbt._bt_ctf_field_get_type(self._f)
 
         if native_field_type is None:
@@ -1171,10 +1187,18 @@ class Field:
 
 
 class IntegerField(Field):
+    """
+    Integer field, based on an :class:`IntegerFieldDeclaration` object.
+    """
+
     @property
     def value(self):
         """
-        Get an integer field's value.
+        Integer value (:class:`int`).
+
+        Set this attribute to change the integer field's value.
+
+        :exc:`ValueError` or :exc:`TypeError` are raised on error.
         """
 
         signedness = nbt._bt_python_field_integer_get_signedness(self._f)
@@ -1194,10 +1218,6 @@ class IntegerField(Field):
 
     @value.setter
     def value(self, value):
-        """
-        Set an integer field's value.
-        """
-
         if not isinstance(value, int):
             raise TypeError("IntegerField's value must be an int")
 
@@ -1215,10 +1235,17 @@ class IntegerField(Field):
 
 
 class EnumerationField(Field):
+    """
+    Enumeration field, based on an
+    :class:`EnumerationFieldDeclaration` object.
+    """
+
     @property
     def container(self):
         """
-        Return the enumeration's underlying container field (an integer field).
+        Underlying container (:class:`IntegerField`).
+
+        :exc:`TypeError` is raised on error.
         """
 
         container = IntegerField.__new__(IntegerField)
@@ -1232,23 +1259,23 @@ class EnumerationField(Field):
     @property
     def value(self):
         """
-        Get the enumeration field's mapping name.
+        Current label of this enumeration field (:class:`str`).
+
+        Set this attribute to an integer (:class:`int`) to change the
+        enumeration field's value.
+
+        :exc:`ValueError` is raised on error.
         """
 
         value = nbt._bt_ctf_field_enumeration_get_mapping_name(self._f)
 
         if value is None:
-            raise ValueError("Could not get enumeration's mapping name.")
+            raise ValueError("Could not get enumeration mapping name.")
 
         return value
 
     @value.setter
     def value(self, value):
-        """
-        Set the enumeration field's value. Must be an integer as mapping names
-        may be ambiguous.
-        """
-
         if not isinstance(value, int):
             raise TypeError("EnumerationField value must be an int")
 
@@ -1256,10 +1283,20 @@ class EnumerationField(Field):
 
 
 class FloatingPointField(Field):
+    """
+    Floating point number field, based on a
+    :class:`FloatingPointFieldDeclaration` object.
+    """
+
     @property
     def value(self):
         """
-        Get a floating point field's value.
+        Floating point number value (:class:`float`).
+
+        Set this attribute to change the floating point number field's
+        value.
+
+        :exc:`ValueError` or :exc:`TypeError` are raised on error.
         """
 
         ret, value = nbt._bt_ctf_field_floating_point_get_value(self._f)
@@ -1271,10 +1308,6 @@ class FloatingPointField(Field):
 
     @value.setter
     def value(self, value):
-        """
-        Set a floating point field's value.
-        """
-
         if not isinstance(value, int) and not isinstance(value, float):
             raise TypeError("Value must be either a float or an int")