Documented Trigger class

Author: azonenberg

scopehal/Trigger.cpp

@@ -1,8 +1,8 @@
 /***********************************************************************************************************************
 *                                                                                                                      *
-* libscopehal v0.1                                                                                                     *
+* libscopehal                                                                                                          *
 *                                                                                                                      *
-* Copyright (c) 2012-2021 Andrew D. Zonenberg and contributors                                                         *
+* Copyright (c) 2012-2024 Andrew D. Zonenberg and contributors                                                         *
 * All rights reserved.                                                                                                 *
 *                                                                                                                      *
 * Redistribution and use in source and binary forms, with or without modification, are permitted provided that the     *
@@ -27,6 +27,13 @@
 *                                                                                                                      *
 ***********************************************************************************************************************/
 
+/**
+	@file
+	@author Andrew D. Zonenberg
+	@brief Implementation of Trigger
+	@ingroup core
+ */
+
 #include "scopehal.h"
 
 using namespace std;
@@ -36,6 +43,11 @@ Trigger::CreateMapType Trigger::m_createprocs;
 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 // Construction / destruction
 
+/**
+	@brief Initialize a new trigger
+
+	@param scope	The scope this trigger is attached to
+ */
 Trigger::Trigger(Oscilloscope* scope)
 	: m_scope(scope)
 	, m_levelname("Level")
@@ -51,24 +63,45 @@ Trigger::~Trigger()
 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 // Enumeration
 
+/**
+	@brief Register a new trigger class for dynamic creation
+
+	Do not call this function directly, use the AddTriggerClass macro
+
+	@param name		Name of the trigger class
+	@param proc		Factory method
+ */
 void Trigger::DoAddTriggerClass(string name, CreateProcType proc)
 {
 	m_createprocs[name] = proc;
 }
 
+/**
+	@brief Gets a list of all registered trigger types
+
+	@param[out] names	List of known triggers
+ */
 void Trigger::EnumTriggers(vector<string>& names)
 {
 	for(CreateMapType::iterator it=m_createprocs.begin(); it != m_createprocs.end(); ++it)
 		names.push_back(it->first);
 }
 
+/**
+	@brief	Creates a new trigger for an oscilloscope
+
+	@param name		Name of the desired trigger
+	@param scope	The scope to create the trigger for
+
+	@return The newly created trigger, or nullptr on failure
+ */
 Trigger* Trigger::CreateTrigger(string name, Oscilloscope* scope)
 {
 	if(m_createprocs.find(name) != m_createprocs.end())
 		return m_createprocs[name](scope);
 
 	LogError("Invalid trigger name: %s\n", name.c_str());
-	return NULL;
+	return nullptr;
 }
 
 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

scopehal/Trigger.h

@@ -1,8 +1,8 @@
 /***********************************************************************************************************************
 *                                                                                                                      *
-* libscopehal v0.1                                                                                                     *
+* libscopehal                                                                                                          *
 *                                                                                                                      *
-* Copyright (c) 2012-2022 Andrew D. Zonenberg and contributors                                                         *
+* Copyright (c) 2012-2024 Andrew D. Zonenberg and contributors                                                         *
 * All rights reserved.                                                                                                 *
 *                                                                                                                      *
 * Redistribution and use in source and binary forms, with or without modification, are permitted provided that the     *
@@ -31,46 +31,76 @@
 	@file
 	@author Andrew D. Zonenberg
 	@brief Declaration of Trigger
+	@ingroup core
  */
 #ifndef Trigger_h
 #define Trigger_h
 
 #include "FlowGraphNode.h"
 
 /**
-	@brief Abstract base class for oscilloscope / logic analyzer triggers
+	@brief Abstract base class for oscilloscope / logic analyzer trigger inputs
+	@ingroup core
  */
 class Trigger : public FlowGraphNode
 {
 public:
 	Trigger(Oscilloscope* scope);
 	virtual ~Trigger();
 
+	///@brief Get the trigger level
 	float GetLevel()
 	{ return m_parameters[m_levelname].GetFloatVal(); }
 
+	/**
+		@brief Sets the trigger level
+
+		@param level	Trigger level
+	 */
 	void SetLevel(float level)
 	{ m_parameters[m_levelname].SetFloatVal(level); }
 
+	///@brief Gets the scope this trigger is attached to
 	Oscilloscope* GetScope()
 	{ return m_scope; }
 
-	//Conditions for filters
+	///@brief Conditions for triggers that perform logical comparisons of values
 	enum Condition
 	{
+		///@brief Match when value is equal to target
 		CONDITION_EQUAL,
+
+		///@brief Match when value is not equal to target
 		CONDITION_NOT_EQUAL,
+
+		///@brief Match when value is less than target
 		CONDITION_LESS,
+
+		///@brief Match when value is less than or equal to target
 		CONDITION_LESS_OR_EQUAL,
+
+		///@brief Match when value is greater than target
 		CONDITION_GREATER,
+
+		///@brief Match when value is greater than or equal to target
 		CONDITION_GREATER_OR_EQUAL,
+
+		///@brief Match when value is greater than one target but less than another
 		CONDITION_BETWEEN,
+
+		///@brief Match when value is not between two targets
 		CONDITION_NOT_BETWEEN,
+
+		///@brief Always match
 		CONDITION_ANY
 	};
 
 protected:
+
+	///@brief The scope this trigger is part of
 	Oscilloscope* m_scope;
+
+	///@brief Name of the "trigger level" parameter
 	std::string m_levelname;
 
 public:
@@ -82,16 +112,13 @@ class Trigger : public FlowGraphNode
 	static void EnumTriggers(std::vector<std::string>& names);
 	static Trigger* CreateTrigger(std::string name, Oscilloscope* scope);
 
-	/**
-		@brief Serializes this trigger's configuration to a YAML string.
-
-		@return YAML block with this trigger's configuration
-	 */
-	virtual YAML::Node SerializeConfiguration(IDTable& table);
+	virtual YAML::Node SerializeConfiguration(IDTable& table) override;
 
 protected:
-	//Class enumeration
+	///@brief Helper typedef for m_createprocs
 	typedef std::map< std::string, CreateProcType > CreateMapType;
+
+	///@brief Map of trigger type names to factory methods
 	static CreateMapType m_createprocs;
 };