@@ -39,6 +39,16 @@ enum field_op_id {
 	FIELD_OP_UNARY_MINUS,
 };
 
+/*
+ * A hist_var (histogram variable) contains variable information for
+ * hist_fields having the HIST_FIELD_FL_VAR or HIST_FIELD_FL_VAR_REF
+ * flag set.  A hist_var has a variable name e.g. ts0, and is
+ * associated with a given histogram trigger, as specified by
+ * hist_data.  The hist_var idx is the unique index assigned to the
+ * variable by the hist trigger's tracing_map.  The idx is what is
+ * used to set a variable's value and, by a variable reference, to
+ * retrieve it.
+ */
 struct hist_var {
 	char				*name;
 	struct hist_trigger_data	*hist_data;

@@ -60,7 +70,15 @@ struct hist_field {
 	char				*system;
 	char				*event_name;
 	char				*name;
-	unsigned int			var_idx;
+
+	/*
+	 * When a histogram trigger is hit, if it has any references
+	 * to variables, the values of those variables are collected
+	 * into a var_ref_vals array by resolve_var_refs().  The
+	 * current value of each variable is read from the tracing_map
+	 * using the hist field's hist_var.idx and entered into the
+	 * var_ref_idx entry i.e. var_ref_vals[var_ref_idx].
+	 */
 	unsigned int			var_ref_idx;
 	bool                            read_once;
 };

@@ -350,6 +368,14 @@ struct action_data {
 	unsigned int		n_params;
 	char			*params[SYNTH_FIELDS_MAX];
 
+	/*
+	 * When a histogram trigger is hit, the values of any
+	 * references to variables, including variables being passed
+	 * as parameters to synthetic events, are collected into a
+	 * var_ref_vals array.  This var_ref_idx is the index of the
+	 * first param in the array to be passed to the synthetic
+	 * event invocation.
+	 */
 	unsigned int		var_ref_idx;
 	struct synth_event	*synth_event;
 	bool			use_trace_keyword;

@@ -362,10 +388,29 @@ struct action_data {
 		} match_data;
 
 		struct {
+			/*
+			 * var_str and var_ref refer to the variable
+			 * being tracked e.g onmax($var).
+			 */
 			char			*var_str;
 			struct hist_field	*var_ref;
+
+			/*
+			 * When a histogram trigger is hit, the values
+			 * of any references to variables, including
+			 * variables being tracked e.g. onmax($var),
+			 * are collected into a var_ref_vals array.
+			 * This var_ref_idx is the index of the
+			 * tracked var value in var_ref_vals, which
+			 * the action can make use of directly.
+			 */
 			unsigned int		var_ref_idx;
 
+			/*
+			 * This track_var contains the 'invisible'
+			 * tracking variable created to keep the
+			 * current e.g. max value.
+			 */
 			struct hist_field	*track_var;
 
 			check_track_val_fn_t	check_val;