Trace View: Add doxygen comments to some classes

diff --git a/pv/views/trace/flag.hpp b/pv/views/trace/flag.hpp
index 4f707bddf3caaa5d9c9fc233950769510041bf21..2df13ca805e3ee74e5a185a372fc55049c7c8c80 100644 (file)
--- a/pv/views/trace/flag.hpp
+++ b/pv/views/trace/flag.hpp
@@ -32,6 +32,10 @@ namespace pv {
 namespace views {
 namespace trace {
 
+/**
+ * The Flag class represents items on the @ref Ruler that mark important
+ * events on the timeline to the user. They are editable and thus non-static.
+ */
 class Flag : public TimeMarker, public enable_shared_from_this<Flag>
 {
        Q_OBJECT

diff --git a/pv/views/trace/header.hpp b/pv/views/trace/header.hpp
index 0038abb1a8f9528825908b794537025fe7d2e518..5d2ba4b7ce1c9e794a5ffa8f27cf1c8b4b02f04c 100644 (file)
--- a/pv/views/trace/header.hpp
+++ b/pv/views/trace/header.hpp
@@ -37,6 +37,12 @@ class TraceTreeItem;
 class View;
 class ViewItem;
 
+/**
+ * The Header class provides an area for @ref Trace labels to be shown,
+ * trace-related settings to be edited, trace groups to be shown and similar.
+ * Essentially, it is the main management area of the @ref View itself and
+ * shown on the left-hand side of the trace area.
+ */
 class Header : public MarginWidget
 {
        Q_OBJECT

diff --git a/pv/views/trace/ruler.hpp b/pv/views/trace/ruler.hpp
index 661254a7280ebd3ce31d0aaac696db9cdc761031..e9432bd6d4208fe66489a9d1ad9963947e88467e 100644 (file)
--- a/pv/views/trace/ruler.hpp
+++ b/pv/views/trace/ruler.hpp
@@ -46,6 +46,11 @@ namespace trace {
 class TimeItem;
 class ViewItem;
 
+/**
+ * The Ruler class manages and displays the time scale above the trace canvas.
+ * It may also contain @ref TimeItem instances used to identify or highlight
+ * time-related information.
+ */
 class Ruler : public MarginWidget
 {
        Q_OBJECT

diff --git a/pv/views/trace/signal.hpp b/pv/views/trace/signal.hpp
index d763609d972abc322dc796e9aca32a2add66269f..7f88720f7943904142008b82d88f8103caefa464 100644 (file)
--- a/pv/views/trace/signal.hpp
+++ b/pv/views/trace/signal.hpp
@@ -44,6 +44,15 @@ class SignalData;
 namespace views {
 namespace trace {
 
+/**
+ * The Signal class represents a series of numeric values that can be drawn.
+ * This is the main difference to the more generic @ref Trace class.
+ *
+ * It is generally accepted that Signal instances consider themselves to be
+ * individual channels on e.g. an oscilloscope, though it should be kept in
+ * mind that virtual signals (e.g. math) will also be served by the Signal
+ * class.
+ */
 class Signal : public Trace, public ViewItemOwner
 {
        Q_OBJECT

diff --git a/pv/views/trace/timeitem.hpp b/pv/views/trace/timeitem.hpp
index dd8d3c4a67c16a982b740475418c9c3827bace12..a9b21c7258ec79ccd9f504ec6883632e1328b709 100644 (file)
--- a/pv/views/trace/timeitem.hpp
+++ b/pv/views/trace/timeitem.hpp
@@ -28,6 +28,10 @@ namespace trace {
 
 class View;
 
+/**
+ * The TimeItem class represents items on the @ref Ruler. It is generic in
+ * nature, not making assumptions about the kind of item shown.
+ */
 class TimeItem : public ViewItem
 
 {

diff --git a/pv/views/trace/timemarker.hpp b/pv/views/trace/timemarker.hpp
index 24ba9b0341bb331b4026f2285a08f423a5aa2059..1a2abb3251e7bc3a8a3caa6e4d63b150141ecffd 100644 (file)
--- a/pv/views/trace/timemarker.hpp
+++ b/pv/views/trace/timemarker.hpp
@@ -41,6 +41,10 @@ namespace trace {
 
 class View;
 
+/**
+ * The TimeMarker class represents items on the @ref Ruler that highlight a
+ * single point in time to the user. Aside from this, it is generic in nature.
+ */
 class TimeMarker : public TimeItem
 {
        Q_OBJECT

diff --git a/pv/views/trace/trace.hpp b/pv/views/trace/trace.hpp
index 88b4ea6b032a7d202896e4aa9264bb0ccb3aa7fe..66a98055d66ac3cde5f34dac53fb7c7a1ad70952 100644 (file)
--- a/pv/views/trace/trace.hpp
+++ b/pv/views/trace/trace.hpp
@@ -49,6 +49,16 @@ class Popup;
 namespace views {
 namespace trace {
 
+/**
+ * The Trace class represents a @ref TraceTreeItem which occupies some vertical
+ * space on the canvas and spans across its entire width, essentially showing
+ * a time series of values, events, objects or similar. While easily confused
+ * with @ref Signal, the difference is that Trace may represent anything that
+ * can be drawn, not just numeric values. One example is a @ref DecodeTrace.
+ *
+ * For this reason, Trace is more generic and contains properties and helpers
+ * that benefit any kind of time series items.
+ */
 class Trace : public TraceTreeItem
 {
        Q_OBJECT

diff --git a/pv/views/trace/triggermarker.hpp b/pv/views/trace/triggermarker.hpp
index dc9c0e9381c997aa99fcce9971529f856e0a4628..f2cee265c5514579fa05f17a329f0210c658720e 100644 (file)
--- a/pv/views/trace/triggermarker.hpp
+++ b/pv/views/trace/triggermarker.hpp
@@ -26,6 +26,10 @@ namespace pv {
 namespace views {
 namespace trace {
 
+/**
+ * The TriggerMarker class is used to show to the user at what point in time
+ * a trigger occured. It is not editable by the user.
+ */
 class TriggerMarker : public TimeItem
 {
        Q_OBJECT