X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=bindings%2Fpython%2Fwriter.py;h=85494bd799cab76fb9a92d6a7399a55c2dd8ddf1;hb=ad9c62de278b38df2ebf30e317412b1adf67d056;hp=d862cd82a4f809c173800379410b4ae9cc9c15cd;hpb=4ac159aa28ef36821c55290056fcab6254bb8d41;p=babeltrace.git

diff --git a/bindings/python/writer.py b/bindings/python/writer.py
index d862cd82..85494bd7 100644
--- a/bindings/python/writer.py
+++ b/bindings/python/writer.py
@@ -1442,20 +1442,24 @@ class SequenceField(Field):
 
 
 class StringField(Field):
+    """
+    String (NULL-terminated array of bytes) field.
+    """
+
     @property
     def value(self):
         """
-        Get a string field's value.
+        String value (:class:`str`).
+
+        Set this attribute to change the string's value.
+
+        :exc:`ValueError` or :exc:`TypeError` are raised on error.
         """
 
         return nbt._bt_ctf_field_string_get_value(self._f)
 
     @value.setter
     def value(self, value):
-        """
-        Set a string field's value.
-        """
-
         ret = nbt._bt_ctf_field_string_set_value(self._f, str(value))
 
         if ret < 0:
@@ -1463,9 +1467,22 @@ class StringField(Field):
 
 
 class EventClass:
+    """
+    An event class contains the properties of specific
+    events (:class:`Event`). Any concrete event must be linked with an
+    :class:`EventClass`.
+
+    Some attributes are automatically set when creating an event class.
+    For example, if no numeric ID is explicitly set using the
+    :attr:`id` attribute, a default, unique ID within the stream class
+    containing this event class will be created when needed.
+    """
+
     def __init__(self, name):
         """
-        Create a new event class of the given name.
+        Creates an event class named *name*.
+
+        :exc:`ValueError` is raised on error.
         """
 
         self._ec = nbt._bt_ctf_event_class_create(name)
@@ -1478,7 +1495,21 @@ class EventClass:
 
     def add_field(self, field_type, field_name):
         """
-        Add a field of type "field_type" to the event class.
+        Adds a field declaration *field_type* named *field_name* to
+        this event class.
+
+        *field_type* must be one of:
+
+        * :class:`IntegerFieldDeclaration`
+        * :class:`FloatingPointFieldDeclaration`
+        * :class:`EnumerationFieldDeclaration`
+        * :class:`StringFieldDeclaration`
+        * :class:`ArrayFieldDeclaration`
+        * :class:`SequenceFieldDeclaration`
+        * :class:`StructureFieldDeclaration`
+        * :class:`VariantFieldDeclaration`
+
+        :exc:`ValueError` is raised on error.
         """
 
         ret = nbt._bt_ctf_event_class_add_field(self._ec, field_type._ft,
@@ -1490,7 +1521,7 @@ class EventClass:
     @property
     def name(self):
         """
-        Get the event class' name.
+        Event class' name.
         """
 
         name = nbt._bt_ctf_event_class_get_name(self._ec)
@@ -1503,7 +1534,13 @@ class EventClass:
     @property
     def id(self):
         """
-        Get the event class' id. Returns a negative value if unset.
+        Event class' numeric ID.
+
+        Set this attribute to assign a numeric ID to this event class.
+        This ID must be unique amongst all the event class IDs of a
+        given stream class.
+
+        :exc:`TypeError` is raised on error.
         """
 
         id = nbt._bt_ctf_event_class_get_id(self._ec)
@@ -1515,21 +1552,18 @@ class EventClass:
 
     @id.setter
     def id(self, id):
-        """
-        Set the event class' id. Throws a TypeError if the event class
-        is already registered to a stream class.
-        """
-
         ret = nbt._bt_ctf_event_class_set_id(self._ec, id)
 
         if ret < 0:
-            raise TypeError("Can't change an Event Class's id after it has been assigned to a stream class")
+            raise TypeError("Can't change an Event Class id after it has been assigned to a stream class")
 
     @property
     def stream_class(self):
         """
-        Get the event class' stream class. Returns None if unset.
+        :class:`StreamClass` object containing this event class,
+        or ``None`` if not set.
         """
+
         stream_class_native = nbt._bt_ctf_event_class_get_stream_class(self._ec)
 
         if stream_class_native is None:
@@ -1543,7 +1577,10 @@ class EventClass:
     @property
     def fields(self):
         """
-        Generator returning the event class' fields as tuples of (field name, field declaration).
+        Generates the (field name, :class:`FieldDeclaration`) pairs of
+        this event class.
+
+        :exc:`TypeError` is raised on error.
         """
 
         count = nbt._bt_ctf_event_class_get_field_count(self._ec)
@@ -1569,7 +1606,10 @@ class EventClass:
 
     def get_field_by_name(self, name):
         """
-        Get a field declaration by name (FieldDeclaration).
+        Returns the :class:`FieldDeclaration` object named *name* in
+        this event class.
+
+        :exc:`TypeError` is raised on error.
         """
 
         field_type_native = nbt._bt_ctf_event_class_get_field_by_name(self._ec, name)