Refinement and documenting

include/ITA/simulation_scheduler/audibility_filter/audibility_filter_interface.h

@@ -38,14 +38,20 @@ namespace ITA
 			class ITA_SIMULATION_SCHEDULER_API IAudibilityFilter
 			{
 			public:
+				///
+				/// \brief Usage mode for audibility filter.
+				/// 
 				enum class UsageMode
 				{
-					filter,
-					condition
+					filter,   ///< Use the audibility filter as an actual filter.
+					condition ///< Use the audibility filter as a condition for following filters.
 				};
 				
 				///
-				/// \brief Configuration class for an audibility filter.
+				/// \brief Base configuration class for audibility filter.
+				///
+				/// \note ::sFilterType is a read only property of the AudibilityFilterConfig.
+				/// Due to this the copy constructor and assignment operator are needed.
 				///
 				struct ITA_SIMULATION_SCHEDULER_API AudibilityFilterConfig : public IConfig
 				{
@@ -77,8 +83,6 @@ namespace ITA
 
 				///
 				/// \brief Check if the change between \p previousState and \p newUpdate is audible.
-				///
-				/// \note Default behaviour it to return false.
 				/// \param previousState the previous state of the scene to check against.
 				/// \param newUpdate the CUpdateScene to check for audibility.
 				/// \return true if the change between \p previousState and \p newUpdate is audible, else false.
@@ -88,6 +92,7 @@ namespace ITA
 			protected:
 				///
 				/// \brief Checks weather the \p newUpdate happened after \p previousState.
+				/// \note This method should be called first in every ::changeIsAudible.
 				/// \throws ITAExcept when \p previousState happened after \p newUpdate.
 				/// \param previousState CUpdateScene of the previous state.
 				/// \param newUpdate new CUpdateScene.
@@ -100,6 +105,7 @@ namespace ITA
 			///
 			/// This class implements an extensible factory for filter.
 			/// After a type of filter is registered with its IAudibilityFilter::createFilter, it can be created using this factory.
+			/// \todo Add a way to get the correct config from the type. The factory already knows of all possible filters.
 			///
 			class ITA_SIMULATION_SCHEDULER_API CAudibilityFilterFactory
 			{

include/ITA/simulation_scheduler/audibility_filter/filter_network.h

@@ -21,9 +21,20 @@ namespace ITA
 
 		namespace audibility_filter
 		{
+			///
+			/// \brief This class models a network of audibility filters.
+			///
+			/// It enables a easy building an evaluation of the configured network.
+			/// The actual network is modeled as a tree.
+			/// Even though in trees paths can not merge, a tree enables an easy way to model the network.
+			/// However, merging paths can still be modeled this way. 
+			/// 
 			class ITA_SIMULATION_SCHEDULER_API CFilterNetwork
 			{
 			public:
+				///
+				/// \brief Configuration class for CFilterNetwork.
+				/// 
 				struct ITA_SIMULATION_SCHEDULER_API FilterNetworkConfig : public IConfig
 				{
 					std::vector<std::shared_ptr<IAudibilityFilter::AudibilityFilterConfig>> vpFilterConfigs;
@@ -41,40 +52,108 @@ namespace ITA
 
 				CFilterNetwork& operator=( const CFilterNetwork& ) = delete;
 
-				CFilterNetwork ( const FilterNetworkConfig& oConfig );
-
+				///
+				/// \brief Constructor for CFilterNetwork.
+				/// \param oConfig the FilterNetworkConfig to configure the CFilterNetwork.
+				/// 
+				explicit CFilterNetwork ( const FilterNetworkConfig& oConfig );
+
+				///
+				/// \brief Evaluate the CFilterNetwork.
+				///
+				/// This method goes through the configured network and checks weather the \p newUpdate is audible.
+				/// \param previousState the previous state of the scene to check against.
+				/// \param newUpdate the CUpdateScene to check.
+				/// \return true if the change between \p previousState and \p newUpdate is audible, else false.
+				/// 
 				bool evaluateNetwork ( const CUpdateScene& previousState, const CUpdateScene& newUpdate );
 
 			private:
+				///
+				/// \brief Tree node used to model the actual network.
+				/// 
 				class NetworkTreeNode
 				{
 				public:
+					///
+					/// \brief Default constructor for NetworkTreeNode. 
+					/// 
 					NetworkTreeNode ( ) = default;
 
+					///
+					/// \brief Constructor for NetworkTreeNode.
+					///
+					/// This constructor set the filter to be executed for the tree node and how it should be used.
+					/// \p bInvertCondition is only used if the UsageMode is set to be a condition.
+					/// \param pFilter the filter to be executed for the tree node.
+					/// \param eUsageMode the UsageMode for the filter.
+					/// \param bInvertCondition true, if the condition should be inverted.
+					/// 
 					NetworkTreeNode ( const IAudibilityFilter* pFilter, IAudibilityFilter::UsageMode eUsageMode, bool bInvertCondition );
 
+					///
+					/// \brief Evaluate the tree nodes filter and its children.
+					///
+					/// This method first evaluates the filter or condition for this node.
+					/// Depending on the result, the children of this node are evaluated next.
+					/// \param previousState the previous state of the scene to check against.
+					/// \param newUpdate the CUpdateScene to check.
+					/// \return true if the change between \p previousState and \p newUpdate is audible, else false.
+					/// 
 					bool evaluate ( const CUpdateScene& previousState, const CUpdateScene& newUpdate );
 
+					///
+					/// \brief Children of the node.
+					/// 
 					std::vector<NetworkTreeNode > vChildren;
 
 				private:
+					///
+					/// \brief The audibility filter of the tree node.
+					/// 
 					const IAudibilityFilter* m_pFilter;
 
+					///
+					/// \brief The usage mode for the filter.
+					/// 
 					IAudibilityFilter::UsageMode m_eUsageMode;
 
+					///
+					/// \brief True, if the condition should be inverted.
+					/// 
 					bool m_bInvertCondition;
 				};
 
+				///
+				/// \brief Create all the actual filter instances that were configured.
+				/// \param vpFilterConfigs vector of all filters that should be created.
+				/// 
 				void createFilters ( const std::vector<std::shared_ptr<IAudibilityFilter::AudibilityFilterConfig>>& vpFilterConfigs );
 
+				///
+				/// \brief Build the network tree.
+				/// \param oConfig configuration from which to build the tree.
+				/// 
 				void buildNetwork ( const FilterNetworkConfig& oConfig );
 
+				///
+				/// \brief Recursive helper method for building the network tree. 
+				/// \param mConfigMap map relating the filter name to its config. 
+				/// \param oRoot the root from which to build the tree.
+				/// \param oRootConfig 
+				/// 
 				void networkBuilderHelper ( const std::map<std::string, std::shared_ptr<IAudibilityFilter::AudibilityFilterConfig>>& mConfigMap,
 											NetworkTreeNode& oRoot,
 											const IAudibilityFilter::AudibilityFilterConfig& oRootConfig );
 
+				///
+				/// \brief Map containing all configured filters, keyed by their names.
+				/// 
 				std::unordered_map<std::string, std::unique_ptr<IAudibilityFilter>> m_mAudibilityFilters;
 
+				///
+				/// \brief The actual network tree of the CFilterNetwork.
+				/// 
 				std::unique_ptr<NetworkTreeNode> m_pNetworkTree;
 			};
 		} // namespace audibility_filter

include/ITA/simulation_scheduler/audibility_filter/rate_filter.h

@@ -30,9 +30,6 @@ namespace ITA
 				///
 				/// \brief Configuration class for the rate filter.
 				///
-				/// This is a basic overload of VistaPropertyList.
-				/// Its main purpose is to distinguish a rate filter config and define its property keys.
-				///
 				struct ITA_SIMULATION_SCHEDULER_API RateFilterConfig : public IAudibilityFilter::AudibilityFilterConfig
 				{
 					explicit RateFilterConfig ( );
@@ -59,7 +56,6 @@ namespace ITA
 				/// \brief Check if the change between \p previousState and \p newUpdate is audible.
 				///
 				/// The change between \p previousState and \p newUpdate is audible when the time between the two updates is larger than the configured rate.
-				/// \remark If the conditions are not fulfilled, the change is not audible.
 				/// \param previousState the previous state of the scene to check against.
 				/// \param newUpdate the CUpdateScene to check for audibility.
 				/// \return true if the change between \p previousState and \p newUpdate is audible, else false.

include/ITA/simulation_scheduler/audibility_filter/reverberation_radius_filter.h

@@ -27,9 +27,6 @@ namespace ITA
 				///
 				/// \brief Configuration class for the reverberation radius filter.
 				///
-				/// This is a basic overload of VistaPropertyList.
-				/// Its main purpose is to distinguish a rate filter config and define its property keys.
-				///
 				struct ITA_SIMULATION_SCHEDULER_API ReverberationRadiusFilterConfig : public IAudibilityFilter::AudibilityFilterConfig
 				{
 					explicit ReverberationRadiusFilterConfig ( );
@@ -55,8 +52,7 @@ namespace ITA
 				///
 				/// \brief Check if the change between \p previousState and \p newUpdate is audible.
 				///
-				/// The change between \p previousState and \p newUpdate is audible when the time between the two updates is larger than the configured rate.
-				/// \remark If the conditions are not fulfilled, the change is not audible.
+				/// The change between \p previousState and \p newUpdate is audible when the receiver resides inside the configured radius around the source.
 				/// \param previousState the previous state of the scene to check against.
 				/// \param newUpdate the CUpdateScene to check for audibility.
 				/// \return true if the change between \p previousState and \p newUpdate is audible, else false.

include/ITA/simulation_scheduler/audibility_filter/rotation_filter.h

@@ -22,10 +22,13 @@ namespace ITA
 			/// \brief Rotation filter
 			///
 			/// This class implements a simple rotation filter.
-			/// First, the azimuth and elevation angle for the source with the receiver as target is calculated and vice versa.
-			/// If the absolute delta between the previous angles and the new angles exceed the configured threshold, the update is deemed audible.
+			/// Depending on the rotation mode, the audibility is checked differently.
+			/// If the relative mode is chosen, first, the azimuth and elevation angle for the source with the receiver as target is calculated and vice versa.
+			/// If the delta between the previous angles and the new angles exceed the configured threshold, the update is deemed audible.
 			///
-			/// For example, consider the use of a 5x5 HRTF.
+			/// If the absolute mode is chosen, just the absolute rotation of source or receiver is checked against the threshold. 
+			///
+			/// For an example, consider the use of a 5x5 HRTF.
 			/// The threshold for the receiver could be set to 2.5 degree to allow a 5 degree "inaudible" zone around the previous angle.
 			/// 
 			class ITA_SIMULATION_SCHEDULER_API CRotationFilter : public IAudibilityFilter
@@ -74,7 +77,6 @@ namespace ITA
 				/// \brief Check if the change between \p previousState and \p newUpdate is audible.
 				///
 				/// The change between \p previousState and \p newUpdate is audible when the rotation of source and receiver exceed the configured thresholds given the configured RotationMode.
-				/// \remark If the conditions are not fulfilled, the change is not audible.
 				/// \param previousState the previous state of the scene to check against.
 				/// \param newUpdate the CUpdateScene to check for audibility.
 				/// \return true if the change between \p previousState and \p newUpdate is audible, else false.

include/ITA/simulation_scheduler/audibility_filter/translation_filter.h

@@ -52,8 +52,7 @@ namespace ITA
 				///
 				/// \brief Check if the change between \p previousState and \p newUpdate is audible.
 				///
-				/// The change between \p previousState and \p newUpdate is audible when the translation length of the translation vector of source or receiver is larger than the configured minimum.
-				/// \remark If the conditions are not fulfilled, the change is not audible.
+				/// The change between \p previousState and \p newUpdate is audible when the length of the translation vector of source or receiver is larger than the configured minimum.
 				/// \param previousState the previous state of the scene to check against.
 				/// \param newUpdate the CUpdateScene to check for audibility.
 				/// \return true if the change between \p previousState and \p newUpdate is audible, else false.

include/ITA/simulation_scheduler/audibility_filter/zone_filter.h

@@ -31,8 +31,6 @@ namespace ITA
 				///
 				/// \brief Configuration class for CZoneFilter.
 				///
-				/// Its main purpose is to distinguish a zone filter config and define its property keys.
-				///
 				struct ITA_SIMULATION_SCHEDULER_API ZoneFilterConfig : AudibilityFilterConfig
 				{
 					explicit ZoneFilterConfig ( );

include/ITA/simulation_scheduler/config_interface.h

@@ -32,4 +32,4 @@ namespace ITA
 	} // namespace simulation_scheduler
 } // namespace ITA
 
-#endif // INCLUDE_WATINCLUDE_WATCHER_ITA_SIMULATION_SCHEDULER_CONFIG_INTERFACECHER_ITA_SIMULATION_SCHEDULER_TYPES
+#endif // INCLUDE_WATCHER_ITA_SIMULATION_SCHEDULER_CONFIG_INTERFACE

include/ITA/simulation_scheduler/room_acoustics/master_simulation_controller.h

@@ -33,15 +33,16 @@ namespace ITA
 		namespace room_acoustics
 		{
 			///
-			/// \brief Primary interaction class.
+			/// \brief Primary interaction class for room acoustic simulations.
 			/// 
-			/// This class represents the interface with which external software should interact with the simulation scheduler.
+			/// This class represents the interface with which external software should interact with the simulation scheduler for room acoustic simulations.
 			/// It allows for easy interaction and configuration of the system.
 			///  - Updates can be issued via postUpdate().
 			///  - A IResultHandler can be registered via attachResultHandler.
 			///  - A simple replacement filter can be enabled for the CMasterSimulationController.
 			///
 			///  The actual computation takes place in its own thread (loop), see LoopBody().
+			///  \todo Inherit the scheduler interface? But we dont need handle simulation here :/ 
 			///
 			class ITA_SIMULATION_SCHEDULER_API CMasterSimulationController : public VistaThreadLoop
 			{

include/ITA/simulation_scheduler/room_acoustics/raven/raven_worker_interface.h

@@ -22,7 +22,7 @@ namespace ITA
 				class CSimulationTask;
 
 				///
-				/// \brief Abstract base for all workers that use raven to simulate updates.
+				/// \brief Interface for room acoustics worker that use raven to simulate updates.
 				/// \todo Add functions to change the config.
 				/// 
 				class ITA_SIMULATION_SCHEDULER_API IRavenWorkerInterface : public IRoomAcousticsWorkerInterface
@@ -30,7 +30,6 @@ namespace ITA
 				public:
 					///
 					/// \brief Configuration class for Raven worker.
-					/// \todo This class might be only used to hold other worker configs. See if we should keep this.
 					/// 
 					struct ITA_SIMULATION_SCHEDULER_API RavenWorkerConfig : public RoomAcousticsWorkerInterfaceConfig
 					{
@@ -49,8 +48,6 @@ namespace ITA
 
 					///
 					/// \brief Constructor for a IRavenWorkerInterface.
-					///
-					/// As we always need a CRavenConfig, this constructor gets passed one. 
 					/// \param oConfig the WorkerConfig used to configure the IWorkerInterface.
 					/// \param pParent the parent scheduler of the worker.
 					/// 

include/ITA/simulation_scheduler/room_acoustics/raven/worker_thread.h

@@ -85,10 +85,10 @@ namespace ITA
 
 					///
 					/// \brief Factory function for CWorkerThread.
-					/// \param oConfig the WorkerConfig used to configure the CWorkerThread.
+					/// \param pConfig the WorkerConfig used to configure the CWorkerThread.
 					/// \param pParent the parent scheduler of the worker.
 					///
-					static std::unique_ptr<IWorkerInterface> createWorker ( const std::shared_ptr<IWorkerInterface::WorkerConfig>& oConfig, ISchedulerInterface* pParent );
+					static std::unique_ptr<IWorkerInterface> createWorker ( const std::shared_ptr<IWorkerInterface::WorkerConfig>& pConfig, ISchedulerInterface* pParent );
 
 					///
 					/// \brief Return a unique type identifying string.

include/ITA/simulation_scheduler/scheduler.h

@@ -44,11 +44,18 @@ namespace ITA
 		///
 		/// CScheduler is kind of the main class of the SimulationScheduler Library.
 		/// This scheduler runs local to where it was created.
-		/// Each CScheduler is responsible for one FieldOfDuty.
-		/// It receives updates, depending on what type od update it is, it either applies the config change (CUpdateConfig), or processes the CUpdateScene.
+		/// 
+		/// It allows for easy interaction and configuration of the system.
+		///  - Updates can be issued via postUpdate().
+		///  - A IResultHandler can be registered via attachResultHandler.
+		///  - A simple replacement filter can be enabled for the CScheduler.
+		///
+		/// It receives updates, depending on what type of update it is, it either applies the config change (CUpdateConfig), or processes the CUpdateScene.
 		/// For this, the CScheduler uses its audibility filters to determine if the update is indeed audible.
 		/// If the update is in fact audible, CScheduler distributes the update to idle workers who actually simulate the update.
 		/// When the update is simulated, the result is passed to all attached result handlers.
+		/// 
+		/// The actual computation takes place in its own thread (loop), see LoopBody().
 		/// \todo Determine where whe save the last simulated update, before sending it to the worker or when receiving it from the worker.
 		/// 
 		class ITA_SIMULATION_SCHEDULER_API CScheduler : public ISchedulerInterface, public VistaThreadLoop
@@ -60,7 +67,7 @@ namespace ITA
 			struct ITA_SIMULATION_SCHEDULER_API LocalSchedulerConfig : public SchedulerConfig
 			{
 				explicit LocalSchedulerConfig ( );
-				
+
 				bool bReplaceUpdates = true;
 
 				std::vector<std::shared_ptr<IWorkerInterface::WorkerConfig>> vpWorkerConfigs;
@@ -109,6 +116,10 @@ namespace ITA
 			/// 
 			virtual void handleSimulationFinished ( std::unique_ptr<CSimulationResult> pResult ) override;
 
+			///
+			/// \brief Return a unique type identifying string.
+			/// \return a unique type identifying string.
+			/// 
 			static std::string getType ( );
 
 		protected:

include/ITA/simulation_scheduler/scheduler_interface.h

@@ -22,7 +22,7 @@ namespace ITA
 		class IResultHandler;
 
 		///
-		/// \brief 
+		/// \brief Interface for a scheduler.
 		/// 
 		class ITA_SIMULATION_SCHEDULER_API ISchedulerInterface
 		{
@@ -30,8 +30,8 @@ namespace ITA
 			///
 			/// \brief Base configuration class for schedulers.
 			///
-			/// This is a basic overload of VistaPropertyList.
-			/// Its main purpose is to distinguish a scheduler config.
+			/// \note ::sSchedulerType is a read only property of the SchedulerConfig.
+			/// Due to this the copy constructor and assignment operator are needed.
 			///
 			struct ITA_SIMULATION_SCHEDULER_API SchedulerConfig : public IConfig
 			{

include/ITA/simulation_scheduler/types.h

@@ -22,6 +22,9 @@ namespace ITA
 
 		namespace room_acoustics
 		{
+			///
+			/// \brief Field of duty of a room acoustic simulation.
+			/// 
 			enum class FieldOfDuty
 			{
 				directSound,

include/ITA/simulation_scheduler/worker_interface.h

@@ -41,9 +41,11 @@ namespace ITA
 		{
 		public:
 			///
-			/// \brief Configuration class for Worker.
-			/// \todo This class might be only used to hold other worker configs. See if we should keep this.
-			/// 
+			/// \brief Base configuration class for worker.
+			///
+			/// \note ::sWorkerType is a read only property of the WorkerConfig.
+			/// Due to this the copy constructor and assignment operator are needed.
+			///
 			struct ITA_SIMULATION_SCHEDULER_API WorkerConfig : public IConfig
 			{
 				WorkerConfig ( );
@@ -107,6 +109,7 @@ namespace ITA
 		///
 		/// This class implements an extensible factory for worker.
 		/// After a type of worker is registered with its IWorkerInterface::createWorker, it can be created using this factory.
+		/// \todo Add a way to get the correct config from the type. The factory already knows of all possible workers.
 		/// 
 		class ITA_SIMULATION_SCHEDULER_API CWorkerFactory
 		{