From: Philippe Proulx <eeppeliteloop@gmail.com>
Date: Tue, 16 Dec 2014 23:12:52 +0000 (-0500)
Subject: Python: document writer.StreamClass
X-Git-Tag: v2.0.0-pre1~1352
X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=commitdiff_plain;h=5fd17f7375186eeba668a7717f6fd062999e3683

Python: document writer.StreamClass

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
---

diff --git a/bindings/python/writer.py b/bindings/python/writer.py
index 567d9266..67b653b4 100644
--- a/bindings/python/writer.py
+++ b/bindings/python/writer.py
@@ -1739,9 +1739,23 @@ class Event:
 
 
 class StreamClass:
+    """
+    A stream class contains the properties of specific
+    streams (:class:`Stream`). Any concrete stream must be linked with
+    a :class:`StreamClass`, usually by calling
+    :meth:`Writer.create_stream`.
+
+    Some attributes are automatically set when creating a stream class.
+    For example, if no clock is explicitly set using the
+    :attr:`clock` attribute, a default clock will be created
+    when needed.
+    """
+
     def __init__(self, name):
         """
-        Create a new stream class of the given name.
+        Creates a stream class named *name*.
+
+        :exc:`ValueError` is raised on error.
         """
 
         self._sc = nbt._bt_ctf_stream_class_create(name)
@@ -1755,7 +1769,9 @@ class StreamClass:
     @property
     def name(self):
         """
-        Get a stream class' name.
+        Stream class' name.
+
+        :exc:`TypeError` is raised on error.
         """
 
         name = nbt._bt_ctf_stream_class_get_name(self._sc)
@@ -1768,7 +1784,11 @@ class StreamClass:
     @property
     def clock(self):
         """
-        Get a stream class' clock.
+        Stream class' clock (:class:`Clock` object).
+
+        Set this attribute to change the clock of this stream class.
+
+        :exc:`ValueError` is raised on error.
         """
 
         clock_instance = nbt._bt_ctf_stream_class_get_clock(self._sc)
@@ -1783,10 +1803,6 @@ class StreamClass:
 
     @clock.setter
     def clock(self, clock):
-        """
-        Assign a clock to a stream class.
-        """
-
         if not isinstance(clock, Clock):
             raise TypeError("Invalid clock type.")
 
@@ -1798,7 +1814,11 @@ class StreamClass:
     @property
     def id(self):
         """
-        Get a stream class' id.
+        Stream class' numeric ID.
+
+        Set this attribute to change the ID of this stream class.
+
+        :exc:`ValueError` is raised on error.
         """
 
         ret = nbt._bt_ctf_stream_class_get_id(self._sc)
@@ -1810,10 +1830,6 @@ class StreamClass:
 
     @id.setter
     def id(self, id):
-        """
-        Assign an id to a stream class.
-        """
-
         ret = nbt._bt_ctf_stream_class_set_id(self._sc, id)
 
         if ret < 0:
@@ -1822,7 +1838,10 @@ class StreamClass:
     @property
     def event_classes(self):
         """
-        Generator returning the stream class' event classes.
+        Generates the event classes (:class:`EventClass` objects) of
+        this stream class.
+
+        :exc:`TypeError` is raised on error.
         """
 
         count = nbt._bt_ctf_stream_class_get_event_class_count(self._sc)
@@ -1843,10 +1862,13 @@ class StreamClass:
 
     def add_event_class(self, event_class):
         """
-        Add an event class to a stream class. New events can be added even after a
-        stream has been instantiated and events have been appended. However, a stream
-        will not accept events of a class that has not been added to the stream
-        class beforehand.
+        Registers the :class:`EventClass` *event_class* to this stream
+        class.
+
+        Once the event class is registered, it will be generated as one
+        of the event classes generated by :attr:`event_classes`.
+
+        :exc:`ValueError` is raised on error.
         """
 
         if not isinstance(event_class, EventClass):
@@ -1861,7 +1883,14 @@ class StreamClass:
     @property
     def packet_context_type(self):
         """
-        Get the StreamClass' packet context type (StructureFieldDeclaration)
+        Stream packet context declaration.
+
+        Set this attribute to change the stream packet context
+        declaration (must be an instance of
+        :class:`StructureFieldDeclaration`).
+
+        :exc:`ValueError` is raised on error.
+
         """
 
         field_type_native = nbt._bt_ctf_stream_class_get_packet_context_type(self._sc)
@@ -1875,11 +1904,6 @@ class StreamClass:
 
     @packet_context_type.setter
     def packet_context_type(self, field_type):
-        """
-        Set a StreamClass' packet context type. Must be of type
-        StructureFieldDeclaration.
-        """
-
         if not isinstance(field_type, StructureFieldDeclaration):
             raise TypeError("field_type argument must be of type StructureFieldDeclaration.")