Merge pull request #83 from DUNE-DAQ/gcrone/documentation_update

Documentation update

Author: mroda88

docs/README.md

@@ -22,27 +22,27 @@ The **Application** class has attributes defining the application's
 ## Resources and ResourceSets
 
 **Resource** is an abstract class describing an item that can be
-disabled directly. It has the method `disabled()` which can be called
+disabled directly. It has the method `is_disabled(const dunedaq::confmodel::ResourceTree& session)` which can be called
 by application code to determine if the object should be considered
-disabled for this session. The [disabling logic](#the-resource-disabled-logic) calls the virtual
-`is_disabled()` method to determine the state of the Resource. The
+disabled for this session (Session is a subclass of ResourceTree). The [disabling logic](#the-resource-disabled-logic) calls the virtual
+`compute_disabled_state(const std::set<std::string>& disabled_resources)` method to determine the state of the Resource, the disabled_resources argument is a list of UIDs of all the Resources that have been disabled so far. The
 implementation provided by the base class just checks that the object
 itself is not in the list of disabled objects. Derived classes can
 re-implement this method with whatever logic is needed to determine the
 state of the object, for example the **ResourceSetDisableAND** class
 provides an implementation that ANDs together the state of all of its
-contained objects.
+contained objects. 
 
 **ResourceSet** is an abstract container of **Resource**s which can be disabled together. It
-is itself a Resource (so can be nested). It defines a pure virtual method `contained_resources()` to get the list of contained resources. Developers should implement this method to extract any resources that need to be considered for determining the disabled state of the set from among the class's relationships. The class may have relationships to other Resource derived
+is itself a Resource (so can be nested). It defines a pure virtual method `contained_resources()` which returns a vector of pointers to 'contained' resources. Developers should implement this method to extract any resources that need to be considered for determining the disabled state of the set from among the class's relationships. The class may have relationships to other Resource derived
 objects that will be ignored for the disabled check.
 
 **ResourceSetDisableAND** is a container of **Resource**s which will
 be disabled if *all* of its **Resource**s are disabled. It provides a
-final implementation of the ResourceSet::is_disabled() method.
+final implementation of the ResourceSet::compute_disabled_state() method.
 
 **ResourceSetDisableOR** is a container of **Resource**s which
-provides a final implementation of the ResourceSet::is_disabled()
+provides a final implementation of the ResourceSet::compute_disabled_state()
 method returning true if *any* of its contained **Resource**s are
 disabled.
 
@@ -73,7 +73,7 @@ are also disabled.
 A list of all ResourceSets in the tree is generated by recursively
 calling `contained_resources()` and iterating over all the ResourceSets.
 Then it iterates over the list of **ResourceSet**s. If a ResourceSet
-is not currently in the disabled set, it will call the `is_disabled()`
+is not currently in the disabled set, it will call the `compute_disabled_state()`
 method to see if its state has been changed by the current content of
 the disabled set. It will repeat this procedure until an iteration
 that ends with the same number of disabled resources it started with.
@@ -95,7 +95,7 @@ single **DetDataReceiver**.
 
 ### Resource handling in the readout map
 
-The **DetectorToDaqConnection** is a **ResourceSet** with a custom implementation of `is_disabled()` that checks that the **DetDataReceiver** and at least one **DetDataSender** are enabled.
+The **DetectorToDaqConnection** is a **ResourceSet** with a custom implementation of `compute_disabled_state()` that checks that the **DetDataReceiver** and at least one **DetDataSender** are enabled.
 
 The **DetDataSender** is a **ResourceSetDisableAND** that contains a set of **DetectorStream** **Resource**s.
 

docs/ReadoutMap.png

@@ -80,7 +80,7 @@
 
 <oks-schema>
 
-<info name="" type="" num-of-items="49" oks-format="schema" oks-version="862f2957270" created-by="jcfree" created-on="mu2edaq13.fnal.gov" creation-time="20230123T223700" last-modified-by="gjc" last-modified-on="latitude" last-modification-time="20250730T085923"/>
+<info name="" type="" num-of-items="49" oks-format="schema" oks-version="862f2957270" created-by="jcfree" created-on="mu2edaq13.fnal.gov" creation-time="20230123T223700" last-modified-by="gjc" last-modified-on="latitude" last-modification-time="20250923T103939"/>
 
  <class name="ActionPlan" description="A set of steps for an application to carry out a command">
   <attribute name="execution_policy" description="How the application should dispatch the command to modules matched by each step of the ActionPlan" type="enum" range="modules-in-parallel,modules-in-series" init-value="modules-in-parallel"/>
@@ -139,7 +139,7 @@
  </class>
 
  <class name="DaqModulesGroup" description="Represents a group of DAQ Modules that can run commands in parallel or in series as one of the steps of an ActionPlan." is-abstract="yes">
-  <attribute name="optional" type="bool" init-value="false" description="When true, the application will not generate a warning message if no modules in the application match this DaqModulesGroup"/>
+  <attribute name="optional" description="When true, the application will not generate a warning message if no modules in the application match this DaqModulesGroup" type="bool" init-value="false"/>
  </class>
 
  <class name="DaqModulesGroupById">
@@ -332,7 +332,7 @@
   <method name="parents" description="The algorithm calculates a vector of segments which are parents of given segment.&#xA;If the segment has parents referenced by the partition object, then:&#xA;- in case of C++ it fills the parents parameter; otherwise it throws {@link NotFoundException} exception">
    <method-implementation language="c++" prototype="void parents(const dunedaq::confmodel::Session&amp; session, std::list&lt; std::vector&lt;const dunedaq::confmodel::Resource *&gt; &gt;&amp; parents) const" body=""/>
   </method>
-  <method name="is_disabled" description="">
+  <method name="is_disabled" description="Method to be called from user code to determine if this Resource is disabled in the current configuration.">
    <method-implementation language="c++" prototype="bool is_disabled(const dunedaq::confmodel::ResourceTree&amp; session) const" body=""/>
   </method>
   <method name="compute_disabled_state" description="Virtual method to be implemented by subclasses containing the logic to determine if this object should be considered disabled.">
@@ -363,10 +363,10 @@
 
  <class name="ResourceTree" is-abstract="yes">
   <relationship name="disabled" description="Resources that should not participate in the current run" class-type="Resource" low-cc="zero" high-cc="many" is-composite="yes" is-exclusive="no" is-dependent="yes"/>
-  <method name="disabled_components" description="">
+  <method name="disabled_components" description="Get a reference to the DisabledResources object of this ResourceTree, initialising it if it has not already been initialised.">
    <method-implementation language="c++" prototype="const dunedaq::confmodel::DisabledResources&amp; disabled_components() const" body="BEGIN_HEADER_PROLOGUE&#xA;#include &quot;confmodel/DisabledResources.hpp&quot;&#xA;#include &quot;confmodel/Resource.hpp&quot;&#xA;END_HEADER_PROLOGUE&#xA;&#xA;BEGIN_PRIVATE_SECTION&#xA;mutable DisabledResources m_disabled_resources;&#xA;END_PRIVATE_SECTION&#xA;&#xA;&#xA;if (!m_disabled_resources.initialised()) {&#xA; m_disabled_resources.update(resource_root(),get_disabled());&#xA;}&#xA;return m_disabled_resources;"/>
   </method>
-  <method name="resource_root" description="">
+  <method name="resource_root" description="Pure virtual method to get the ResourceSet at the root of the ResourceTree.">
    <method-implementation language="c++" prototype="virtual const ResourceSet* resource_root() const = 0" body=""/>
   </method>
  </class>