From: Soeren Apel <redacted>
Date: Sun, 23 Jul 2017 20:17:16 +0000 (+0200)
Subject: Trace View: Add doxygen comments to some classes
X-Git-Url: https://sigrok.org/gitaction?a=commitdiff_plain;h=1373fec59223e7511078abe3dbf4a6b61b4af234;p=pulseview.git

Trace View: Add doxygen comments to some classes
---

diff --git a/pv/views/trace/flag.hpp b/pv/views/trace/flag.hpp
index 4f707bdd..2df13ca8 100644
--- 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 0038abb1..5d2ba4b7 100644
--- 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 661254a7..e9432bd6 100644
--- 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 d763609d..7f88720f 100644
--- 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 dd8d3c4a..a9b21c72 100644
--- 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 24ba9b03..1a2abb32 100644
--- 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 88b4ea6b..66a98055 100644
--- 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 dc9c0e93..f2cee265 100644
--- 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