From 5d9ce304699f07a7203ca4ceb246b482720c031e Mon Sep 17 00:00:00 2001
From: Brian Norris <banorris@uci.edu>
Date: Thu, 21 Jun 2012 02:37:47 -0700
Subject: [PATCH] clockvector: add documentation

---
 clockvector.cc | 21 +++++++++++++++++++++
 clockvector.h  |  3 +++
 2 files changed, 24 insertions(+)

diff --git a/clockvector.cc b/clockvector.cc
index 2ef8b03..c7cc183 100644
--- a/clockvector.cc
+++ b/clockvector.cc
@@ -7,6 +7,14 @@
 #include "clockvector.h"
 #include "common.h"
 
+/**
+ * Constructs a new ClockVector, given a parent ClockVector and a first
+ * ModelAction. This constructor can assign appropriate default settings if no
+ * parent and/or action is supplied.
+ * @param parent is the previous ClockVector to inherit (i.e., clock from the
+ * same thread or the parent that created this thread)
+ * @param act is an action with which to update the ClockVector
+ */
 ClockVector::ClockVector(ClockVector *parent, ModelAction *act)
 {
 	num_threads = model->get_num_threads();
@@ -19,11 +27,17 @@ ClockVector::ClockVector(ClockVector *parent, ModelAction *act)
 		clock[id_to_int(act->get_tid())] = act->get_seq_number();
 }
 
+/** @brief Destructor */
 ClockVector::~ClockVector()
 {
 	MYFREE(clock);
 }
 
+/**
+ * Merge a clock vector into this vector, using a pairwise vector. The
+ * resulting vector length will be the maximum length of the two being merged.
+ * @param cv is the ClockVector being merged into this vector.
+ */
 void ClockVector::merge(ClockVector *cv)
 {
 	int *clk = clock;
@@ -50,6 +64,12 @@ void ClockVector::merge(ClockVector *cv)
 }
 
 /**
+ * Check whether this vector's thread has synchronized with another action's
+ * thread. This effectively checks the happens-before relation (or actually,
+ * happens after), but it's easier to compare two ModelAction events directly,
+ * using ModelAction::happens_before.
+ *
+ * @see ModelAction::happens_before
  *
  * @return true if this ClockVector's thread has synchronized with act's
  * thread, false otherwise. That is, this function returns:
@@ -64,6 +84,7 @@ bool ClockVector::synchronized_since(ModelAction *act)
 	return false;
 }
 
+/** @brief Formats and prints this ClockVector's data. */
 void ClockVector::print()
 {
 	int i;
diff --git a/clockvector.h b/clockvector.h
index d233cdd..7f32b7e 100644
--- a/clockvector.h
+++ b/clockvector.h
@@ -22,7 +22,10 @@ public:
 
 	MEMALLOC
 private:
+	/** @brief Holds the actual clock data, as an array. */
 	int *clock;
+
+	/** @brief The number of threads recorded in clock (i.e., its length).  */
 	int num_threads;
 };
 
-- 
2.34.1