a/util: Improve word choice/clarity

src/xrt/auxiliary/util/u_builders.c

@@ -66,7 +66,7 @@ u_builder_search(struct xrt_prober *xp,
 
 		results->xpdevs[results->xpdev_count++] = xpdev;
 
-		// Abort if full.
+		// Exit if full.
 		if (results->xpdev_count >= ARRAY_SIZE(results->xpdevs)) {
 			return;
 		}

src/xrt/auxiliary/util/u_device.c

@@ -214,7 +214,7 @@ u_device_setup_split_side_by_side(struct xrt_device *xdev, const struct u_device
 		}
 	}
 	{
-		/* left eye - just mirroring right eye now */
+		/* left eye - mirroring right eye */
 		xdev->hmd->distortion.fov[0].angle_up = xdev->hmd->distortion.fov[1].angle_up;
 		xdev->hmd->distortion.fov[0].angle_down = xdev->hmd->distortion.fov[1].angle_down;
 

src/xrt/auxiliary/util/u_device.h

@@ -76,7 +76,7 @@ bool
 u_device_setup_split_side_by_side(struct xrt_device *xdev, const struct u_device_simple_info *info);
 
 /*!
- * Just setup the device's display's 2D extents.
+ * Setup the device's display's 2D extents.
  * Good for headsets without traditional VR optics.
  *
  * @return true on success.

src/xrt/auxiliary/util/u_distortion.h

@@ -60,7 +60,7 @@ struct u_cardboard_distortion_arguments
  * Values to create a distortion mesh from cardboard values.
  *
  * This matches the formula in the cardboard SDK, while the array is fixed size
- * just setting the K value to zero will make it not have a effect.
+ * setting the K value to zero will make it not have a effect.
  *
  *    p' = p (1 + K0 r^2 + K1 r^4 + ... + Kn r^(2n))
  *

src/xrt/auxiliary/util/u_documentation.h

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: BSL-1.0
 /*!
  * @file
- * @brief  Header with just documentation.
+ * @brief  Header with only documentation.
  * @author Jakob Bornecrantz <jakob@collabora.com>
  * @ingroup aux_util
  */

src/xrt/auxiliary/util/u_frame.c

@@ -56,7 +56,7 @@ u_frame_clone(struct xrt_frame *to_copy, struct xrt_frame **out_frame)
 {
 	struct xrt_frame *xf = U_TYPED_CALLOC(struct xrt_frame);
 
-	// Paranoia: Explicitly only copy the fields we want
+	// Explicitly only copy the fields we want
 	xf->width = to_copy->width;
 	xf->height = to_copy->height;
 	xf->stride = to_copy->stride;

src/xrt/auxiliary/util/u_hashset.cpp

@@ -81,12 +81,12 @@ u_hashset_insert_item(struct u_hashset *hs, struct u_hashset_item *item)
 extern "C" int
 u_hashset_create_and_insert_str(struct u_hashset *hs, const char *str, size_t length, struct u_hashset_item **out_item)
 {
-	struct u_hashset_item *dummy = NULL;
+	struct u_hashset_item *unused = NULL;
 	struct u_hashset_item *item = NULL;
 	size_t size = 0;
 	int ret;
 
-	ret = u_hashset_find_str(hs, str, length, &dummy);
+	ret = u_hashset_find_str(hs, str, length, &unused);
 	if (ret >= 0) {
 		return -1;
 	}

src/xrt/auxiliary/util/u_id_ringbuffer.cpp

@@ -31,7 +31,7 @@ struct u_id_ringbuffer
 
 namespace {
 
-// just enough iterator to get it done: basically copy and paste from u_template_historybuf_const_iterator.inl
+// just-enough iterator to get it done: basically copy and paste from u_template_historybuf_const_iterator.inl
 struct IdRingbufferIterator : public RandomAccessIteratorBase<const RingBufferHelper>
 {
 	using base = RandomAccessIteratorBase<const RingBufferHelper>;

src/xrt/auxiliary/util/u_id_ringbuffer.h

@@ -19,7 +19,7 @@ extern "C" {
 /**
  * Container type to let you store IDs in a ring buffer, and maybe your own data in your own parallel array.
  *
- * The IDs are just uint64_t. If you don't need any of the order-dependent functionality, you can treat use them for any
+ * The IDs are uint64_t. If you don't need any of the order-dependent functionality, you can treat use them for any
  * purpose you like.
  *
  * Some functionality requires that IDs be pushed in increasing order, but it's highlighted in the docs.
@@ -187,7 +187,7 @@ u_id_ringbuffer_lower_bound_id(struct u_id_ringbuffer *uirb, uint64_t search_id,
 /**
  * Find the element with the supplied ID @p search_id in an unordered buffer.
  *
- * This does *not* depend on order so just does a linear search. If you are keeping your IDs in ascending order, use
+ * This does *not* depend on order so does a linear search. If you are keeping your IDs in ascending order, use
  * u_id_ringbuffer_lower_bound_id() instead.
  *
  * @param uirb self pointer

src/xrt/auxiliary/util/u_iterator_base.hpp

@@ -65,7 +65,7 @@ public:
 	}
 
 	/*!
-	 * @brief True if this iterator is "irrecoverably" invalid (aka, cleared/default constructed).
+	 * @brief True if this iterator is "irrecoverably" invalid (that is, cleared or default constructed).
 	 *
 	 * Implies !valid() but is stronger. `buf.end().is_cleared()` is false.
 	 */
@@ -128,7 +128,8 @@ public:
 
 
 	/**
-	 * @brief Default constructor - initializes to "cleared" aka irrecoverably invalid
+	 * @brief Default constructor - initializes to "cleared" (that is, irrecoverably invalid - because we have no
+	 * reference to a container)
 	 */
 	RandomAccessIteratorBase() = default;
 
@@ -172,7 +173,7 @@ protected:
 	void
 	decrement_n(std::size_t n);
 
-	//! Access the container or helper
+	//! Get the associated container or helper
 	ContainerOrHelper *
 	container() const noexcept
 	{

src/xrt/auxiliary/util/u_json.hpp

@@ -89,7 +89,7 @@ private:
 public:
 	// Class resource management
 
-	//! This is public just so that make_shared works; do not use outside of this file.
+	//! This is public so that make_shared works; do not use outside of this file.
 	JSONNode(cJSON *cjson, bool is_owner, const JSONNode::Ptr &parent)
 	    : cjson(cjson), is_owner(is_owner), parent(parent)
 	{}
@@ -190,7 +190,7 @@ public:
 	operator[](const string &key) const
 	{
 		const char *name = key.c_str();
-		JSON_ASSERTW(isObject(), "Trying to access field '%s' from non-object %s", name, toString().c_str());
+		JSON_ASSERTW(isObject(), "Trying to retrieve field '%s' from non-object %s", name, toString().c_str());
 
 		cJSON *value = cJSON_GetObjectItemCaseSensitive(cjson, name);
 		JSON_ASSERTW(value != nullptr, "Unable to retrieve field '%s' from %s", name, toString().c_str());
@@ -201,7 +201,7 @@ public:
 	JSONNode
 	operator[](int i) const
 	{
-		JSON_ASSERTW(isArray(), "Trying to access index '%d' from non-array %s", i, toString().c_str());
+		JSON_ASSERTW(isArray(), "Trying to retrieve index '%d' from non-array %s", i, toString().c_str());
 
 		cJSON *value = cJSON_GetArrayItem(cjson, i);
 		JSON_ASSERTW(value != nullptr, "Unable to retrieve index %d from %s", i, toString().c_str());
@@ -427,7 +427,7 @@ private:
 	 * @brief Receives inputs and transitions the automata from state to state.
 	 *
 	 * This is the table of transitions. Can be thought of as three regular FSM
-	 * that get switched based on the stack's [top] value. The function is just
+	 * that get switched based on the stack's [top] value. The function is
 	 * the implementation of the table.
 	 *
 	 * [top],  [state],          [symbol]    -> [new-state],      [stack-action]

src/xrt/auxiliary/util/u_logging.h

@@ -66,7 +66,7 @@ typedef void (*u_log_sink_func_t)(const char *file,
                                   void *data);
 
 /*!
- * For places where you really just want printf, prints a new-line.
+ * For places where you really want printf, prints a new-line.
  */
 #define U_LOG_RAW(...)                                                                                                 \
 	do {                                                                                                           \

src/xrt/auxiliary/util/u_misc.h

@@ -80,7 +80,7 @@ extern "C" {
 /*!
  * Reallocates or frees dynamically-allocated memory.
  *
- * Just wraps realloc with a return value check, freeing the provided memory if
+ * Wraps realloc with a return value check, freeing the provided memory if
  * it is NULL, to avoid leaks. Use U_ARRAY_REALLOC_OR_FREE() instead.
  *
  * @ingroup aux_util

src/xrt/auxiliary/util/u_pacing.h

@@ -120,7 +120,7 @@ struct u_pacing_compositor
 	 * @param[in] earliest_present_time_ns The earliest the GPU could have presented - might be before @p
 	 *                                     actual_present_time_ns if a @p desired_present_time_ns was passed.
 	 * @param[in] present_margin_ns        How "early" present happened compared to when it needed to happen in
-	 *                                     order to hit @p earliestPresentTime.
+	 *                                     order to finish at @p earliestPresentTime.
 	 * @param[in] when_ns                  The time when we got the info, nominally from @ref
 	 *                                     os_monotonic_get_ns
 	 *

src/xrt/auxiliary/util/u_pacing_compositor.c

@@ -645,7 +645,7 @@ static void
 pc_update_vblank_from_display_control(struct u_pacing_compositor *upc, uint64_t last_vblank_ns)
 {
 	/*
-	 * This is a no-op, here just in case display control is used at the
+	 * This is a no-op, here in case display control is used at the
 	 * same time as the google extension. We ignore this call.
 	 */
 }
@@ -670,7 +670,7 @@ pc_destroy(struct u_pacing_compositor *upc)
 }
 
 const struct u_pc_display_timing_config U_PC_DISPLAY_TIMING_CONFIG_DEFAULT = {
-    // Just a wild guess.
+    // An arbitrary guess.
     .present_to_display_offset_ns = U_TIME_1MS_IN_NS * 4,
     .margin_ns = U_TIME_1MS_IN_NS,
     // Start by assuming the compositor takes 10% of the frame.
@@ -695,12 +695,13 @@ u_pc_display_timing_create(uint64_t estimated_frame_period_ns,
 	pc->base.destroy = pc_destroy;
 	pc->frame_period_ns = estimated_frame_period_ns;
 
-	// Estimate of how long after "present" the photons hit the eyes
+	// Estimate of how long after "present" the eyes see the photons
 	pc->present_to_display_offset_ns = config->present_to_display_offset_ns;
 
 	// Start at this of frame time.
 	pc->comp_time_ns = get_percent_of_time(estimated_frame_period_ns, config->comp_time_fraction);
-	// Max compositor time: if we ever hit this, write a better compositor.
+	// Max compositor time: if we ever reach this, write a better compositor. (using too much time per frame on the
+	// compositor)
 	pc->comp_time_max_ns = get_percent_of_time(estimated_frame_period_ns, config->comp_time_max_fraction);
 	// When missing, back off in these increments
 	pc->adjust_missed_ns = get_percent_of_time(estimated_frame_period_ns, config->adjust_missed_fraction);

src/xrt/auxiliary/util/u_pacing_compositor_fake.c

@@ -202,7 +202,7 @@ u_pc_fake_create(uint64_t estimated_frame_period_ns, uint64_t now_ns, struct u_p
 	// To make sure the code can start from a non-zero frame id.
 	ft->frame_id_generator = 5;
 
-	// Just a wild guess.
+	// An arbitrary guess.
 	ft->present_to_display_offset_ns = U_TIME_1MS_IN_NS * 4;
 
 	// 20% of the frame time.

src/xrt/auxiliary/util/u_process.h

@@ -21,7 +21,7 @@ struct u_process;
  * Creates a handle for this process that is unique to the operating system user. Returns NULL if another process
  * holding a handle is already running.
  *
- * @todo If built without libbsd support, a dummy value is returned that needs to be handled by the caller.
+ * @todo If built without libbsd support, a placeholder value is returned that needs to be handled by the caller.
  *
  * @return a new u_process handle if no monado instance is running, NULL if another instance is already running.
  * @ingroup aux_util

src/xrt/auxiliary/util/u_sink_force_genlock.c

@@ -74,7 +74,6 @@ force_genlock_mainloop(void *ptr)
 			break;
 		}
 
-		// Just in case.
 		if (q->frames[0] == NULL || q->frames[1] == NULL) {
 			continue;
 		}
@@ -85,7 +84,7 @@ force_genlock_mainloop(void *ptr)
 		 * We need to take a reference on the current frame, this is to
 		 * keep it alive during the call to the consumer should it be
 		 * replaced. But we no longer need to hold onto the frame on the
-		 * queue so we just move the pointer.
+		 * queue so we move the pointer.
 		 */
 		frames[0] = q->frames[0];
 		frames[1] = q->frames[1];
@@ -124,7 +123,7 @@ force_genlock_mainloop(void *ptr)
 
 		/*
 		 * Average the timestamps, SLAM systems break if they don't have the exact same timestamp.
-		 * (This is dumb, because on DepthAI the images *are* taken like 0.1ms apart, and we *could* expose
+		 * (This is not great, because on DepthAI the images *are* taken like 0.1ms apart, and we *could* expose
 		 * that, but oh well.)
 		 */
 

src/xrt/auxiliary/util/u_sink_queue.c

@@ -148,7 +148,6 @@ queue_mainloop(void *ptr)
 			break;
 		}
 
-		// Just in case.
 		if (queue_is_empty(q)) {
 			continue;
 		}
@@ -160,7 +159,7 @@ queue_mainloop(void *ptr)
 		 * We need to take a reference on the current frame, this is to
 		 * keep it alive during the call to the consumer should it be
 		 * replaced. But we no longer need to hold onto the frame on the
-		 * queue so we just dequeue it.
+		 * queue so we dequeue it.
 		 */
 		frame = queue_pop(q);
 

src/xrt/auxiliary/util/u_sink_simple_queue.c

@@ -86,7 +86,7 @@ queue_mainloop(void *ptr)
 		 * We need to take a reference on the current frame, this is to
 		 * keep it alive during the call to the consumer should it be
 		 * replaced. But we no longer need to hold onto the frame on the
-		 * queue so we just move the pointer.
+		 * queue so we move the pointer.
 		 */
 		frame = q->frame;
 		q->frame = NULL;

src/xrt/auxiliary/util/u_string_list.h

@@ -107,7 +107,7 @@ u_string_list_append_array(struct u_string_list *usl, const char *const *arr, ui
 /*!
  * @brief Append a new string literal to the list, if it's not the same as a string already in the list.
  *
- * (Comparing string contents, not just pointers)
+ * (Comparing string contents, not pointers)
  *
  * @param usl self pointer
  * @param str a non-null, null-terminated string that must live at least as long as the list, preferably a string
@@ -122,7 +122,7 @@ u_string_list_append_unique(struct u_string_list *usl, const char *str);
 /*!
  * @brief Check if the string is in the list.
  *
- * (Comparing string contents, not just pointers)
+ * (Comparing string contents, not pointers)
  *
  * @param usl self pointer
  * @param str a non-null, null-terminated string.

src/xrt/auxiliary/util/u_string_list.hpp

@@ -111,7 +111,7 @@ public:
 	/*!
 	 * @brief Check if the string is in the list.
 	 *
-	 * (Comparing string contents, not just pointers)
+	 * (Comparing string contents, not pointers)
 	 *
 	 * @param str a non-null, null-terminated string.
 	 *
@@ -131,7 +131,7 @@ public:
 	/*!
 	 * @brief Append a new string to the list if it doesn't match any existing string.
 	 *
-	 * (Comparing string contents, not just pointers)
+	 * (Comparing string contents, not pointers)
 	 *
 	 * This does a simple linear search, because it is assumed that the size of this list is fairly small.
 	 *

src/xrt/auxiliary/util/u_template_historybuf.hpp

@@ -69,7 +69,7 @@ public:
 	/*!
 	 * @brief Logically remove the oldest element from the buffer.
 	 *
-	 * The value still remains in the backing container until overwritten, it just isn't accessible anymore.
+	 * The value still remains in the backing container until overwritten, but it isn't accessible anymore.
 	 *
 	 * This invalidates iterators. They won't be poisoned, but they will return something you don't expect.
 	 */
@@ -80,7 +80,7 @@ public:
 	}
 
 	/*!
-	 * @brief Access something at a given age, where age 0 is the most recent value, age 1 precedes it, etc.
+	 * @brief Use a value at a given age, where age 0 is the most recent value, age 1 precedes it, etc.
 	 * (reverse chronological order)
 	 *
 	 * Out of bounds accesses will return nullptr.
@@ -94,7 +94,6 @@ public:
 
 	/*!
 	 * @brief Like get_at_age() but values larger than the oldest age are clamped.
-	 *
 	 */
 	T *
 	get_at_clamped_age(size_t age) noexcept
@@ -118,7 +117,7 @@ public:
 	}
 
 	/*!
-	 * @brief Access something at a given index, where 0 is the least-recent value still stored, index 1 follows it,
+	 * @brief Use a value at a given index, where 0 is the least-recent value still stored, index 1 follows it,
 	 * etc. (chronological order)
 	 *
 	 * Out of bounds accesses will return nullptr.

src/xrt/auxiliary/util/u_template_historybuf_const_iterator.inl

@@ -64,7 +64,7 @@ namespace detail {
 			return valid();
 		}
 
-		//! Access the container: for internal use
+		//! Get the inner container: for internal use
 		container_type *
 		container() const noexcept
 		{

src/xrt/auxiliary/util/u_template_historybuf_impl_helpers.hpp

@@ -178,7 +178,7 @@ RingBufferHelper::index_to_inner_index(size_t index, size_t &out_inner_idx) cons
 	if (index >= length_) {
 		return false;
 	}
-	// Just add to the front (oldest) index and take modulo capacity_
+	// add to the front (oldest) index and take modulo capacity_
 	out_inner_idx = (front_impl_() + index) % capacity_;
 	return true;
 }
@@ -188,7 +188,7 @@ RingBufferHelper::push_back_location() noexcept
 {
 	// We always increment the latest inner index modulo capacity_
 	latest_inner_idx_ = (latest_inner_idx_ + 1) % capacity_;
-	// Length cannot exceed capacity_. If it already was capacity_, that just means we're overwriting something at
+	// Length cannot exceed capacity_. If it already was capacity_, that means we're overwriting something at
 	// latest_inner_idx_
 	length_ = std::min(length_ + 1, capacity_);
 	return latest_inner_idx_;

src/xrt/auxiliary/util/u_template_historybuf_iterator.inl

@@ -60,7 +60,7 @@ namespace detail {
 			return valid();
 		}
 
-		//! Access the container: for internal use
+		//! Get the associated container: for internal use
 		container_type *
 		container() const noexcept
 		{

src/xrt/auxiliary/util/u_var.h

@@ -175,11 +175,9 @@ typedef void (*u_var_elm_cb)(struct u_var_info *info, void *);
  * side-effects.
  *
  * This is intended only for debugging and is turned off by default, as this all
- * very very unsafe. It is just pointers straight into objects, completely
+ * very very unsafe. It is only pointers straight into objects, completely
  * ignores ownership or any safe practices.
  *
- * If it's stupid, but it works, it ain't stupid.
- *
  * ```c
  * // On create
  * u_var_add_root((void*)psmv, "PS Move Controller", true);

src/xrt/auxiliary/util/u_win32_com_guard.cpp

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: BSL-1.0
 /*!
  * @file
- * @brief An object that serves to keep the reference count of COM initialization above 0.
+ * @brief An object that serves to keep the reference count of COM initialization greater than 0.
  *
  * @author Ryan Pavlik <ryan.pavlik@collabora.com>
  * @ingroup aux_util

src/xrt/auxiliary/util/u_win32_com_guard.hpp

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: BSL-1.0
 /*!
  * @file
- * @brief An object that serves to keep the reference count of COM initialization above 0.
+ * @brief An object that serves to keep the reference count of COM initialization greater than 0.
  *
  * @author Ryan Pavlik <ryan.pavlik@collabora.com>
  * @ingroup aux_util

src/xrt/auxiliary/util/u_worker.c

@@ -217,7 +217,7 @@ locked_group_should_wait(struct pool *p, struct group *g)
 	 * work is outstanding what we should do then is increase the worker
 	 * limit and wait on the conditional.
 	 *
-	 * Similar to above, we where woken up, there are more work outstanding
+	 * Similar to preceding, we were woken up, there are more work outstanding
 	 * on the group and we had been released, remove one released and up the
 	 * worker limit, then wait on the conditional.
 	 *
@@ -225,7 +225,7 @@ locked_group_should_wait(struct pool *p, struct group *g)
 	 * submitted, then break out of the loop and decrement the released
 	 * count.
 	 *
-	 * As above, but we where one of many woken up but only one thread had
+	 * As preceding, but we were one of many woken up but only one thread had
 	 * been released and that released count had been taken, then we should
 	 * do nothing and wait again.
 	 */