From: Philippe Proulx <eeppeliteloop@gmail.com>
Date: Wed, 10 Dec 2014 01:27:27 +0000 (-0500)
Subject: Python: document writer.StructureFieldDeclaration
X-Git-Tag: v2.0.0-pre1~1368
X-Git-Url: http://git.efficios.com/?a=commitdiff_plain;h=18449dbf1166bb346fee4f8be333ae96ac3460f4;p=babeltrace.git

Python: document writer.StructureFieldDeclaration

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 7c6627e0..9bf9e688 100644
--- a/bindings/python/writer.py
+++ b/bindings/python/writer.py
@@ -745,9 +745,16 @@ class FloatFieldDeclaration(FloatingPointFieldDeclaration):
 
 
 class StructureFieldDeclaration(FieldDeclaration):
+    """
+    Structure field declaration, i.e. an ordered mapping from field
+    names to field declarations.
+    """
+
     def __init__(self):
         """
-        Create a new structure field declaration.
+        Creates an empty structure field declaration.
+
+        :exc:`ValueError` is raised on error.
         """
 
         self._ft = nbt._bt_ctf_field_type_structure_create()
@@ -755,7 +762,10 @@ class StructureFieldDeclaration(FieldDeclaration):
 
     def add_field(self, field_type, field_name):
         """
-        Add a field of type "field_type" to the structure.
+        Appends one :class:`FieldDeclaration` *field_type* named
+        *field_name* to the structure's ordered map.
+
+        :exc:`ValueError` is raised on error.
         """
 
         ret = nbt._bt_ctf_field_type_structure_add_field(self._ft,
@@ -768,7 +778,10 @@ class StructureFieldDeclaration(FieldDeclaration):
     @property
     def fields(self):
         """
-        Generator returning the structure's field as tuples of (field name, field declaration).
+        Generates the (field name, :class:`FieldDeclaration`) pairs
+        of this structure.
+
+        :exc:`TypeError` is raised on error.
         """
 
         count = nbt._bt_ctf_field_type_structure_get_field_count(self._ft)
@@ -794,7 +807,10 @@ class StructureFieldDeclaration(FieldDeclaration):
 
     def get_field_by_name(self, name):
         """
-        Get a field declaration by name (FieldDeclaration).
+        Returns the :class:`FieldDeclaration` mapped to the field name
+        *name* in this structure.
+
+        :exc:`TypeError` is raised on error.
         """
 
         field_type_native = nbt._bt_ctf_field_type_structure_get_field_type_by_name(self._ft, name)