From d5e16d9bedf9e5ac75ec38e0179fa60bedd98309 Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Fri, 5 Dec 2014 19:51:10 -0500 Subject: [PATCH] Python: document TraceHandle MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Philippe Proulx Signed-off-by: Jérémie Galarneau --- bindings/python/bt.py | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/bindings/python/bt.py b/bindings/python/bt.py index db1274dac..c1a9b3e82 100644 --- a/bindings/python/bt.py +++ b/bindings/python/bt.py @@ -252,9 +252,9 @@ class _ClockType: class TraceHandle: """ - The TraceHandle allows the user to manipulate a trace file directly. - It is a unique identifier representing a trace file. - Do not instantiate. + A :class:`TraceHandle` is a handle allowing the user to manipulate + a specific trace directly. It is a unique identifier representing a + trace, and is not meant to be instantiated by the user. """ def __init__(self): @@ -265,20 +265,27 @@ class TraceHandle: @property def id(self): - """Return the TraceHandle id.""" + """ + Trace handle's numeric ID. + """ return self._id @property def path(self): - """Return the path of a TraceHandle.""" + """ + Path of the underlying trace. + """ return nbt._bt_trace_handle_get_path(self._trace_collection._tc, self._id) @property def timestamp_begin(self): - """Return the creation time of the buffers of a trace.""" + """ + Buffers creation timestamp (nanoseconds since Epoch) of the + underlying trace. + """ return nbt._bt_trace_handle_get_timestamp_begin(self._trace_collection._tc, self._id, @@ -286,7 +293,10 @@ class TraceHandle: @property def timestamp_end(self): - """Return the destruction timestamp of the buffers of a trace.""" + """ + Buffers destruction timestamp (nanoseconds since Epoch) of the + underlying trace. + """ return nbt._bt_trace_handle_get_timestamp_end(self._trace_collection._tc, self._id, @@ -295,7 +305,11 @@ class TraceHandle: @property def events(self): """ - Generator returning all events (EventDeclaration) in a trace. + Generates all the :class:`EventDeclaration` objects of the + underlying trace. + + Note that this doesn't generate actual trace *events*, but + rather their declarations, i.e. their layouts and metadata. """ ret = nbt._bt_python_event_decl_listcaller(self.id, -- 2.34.1