docs: fix documentation issues

Aplib.Core/Agents/BdiAgent.cs

@@ -13,7 +13,7 @@ public class BdiAgent<TBeliefSet> : IAgent
         where TBeliefSet : IBeliefSet
     {
         /// <summary>
-        /// Gets the beliefset of the agent.
+        /// Gets the belief set of the agent.
         /// </summary>
         private readonly TBeliefSet _beliefSet;
 
@@ -29,10 +29,11 @@ public class BdiAgent<TBeliefSet> : IAgent
         public CompletionStatus Status => _desireSet.Status;
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="BdiAgent{TBeliefSet}" /> class.
+        /// Initializes a new instance of the <see cref="BdiAgent{TBeliefSet}" /> class,
+        /// from a given set of beliefs and desires.
         /// </summary>
-        /// <param name="beliefSet">The beliefset of the agent.</param>
-        /// <param name="desireSet"></param>
+        /// <param name="beliefSet">The belief set of the agent.</param>
+        /// <param name="desireSet">The desire set of the agent.</param>
         public BdiAgent(TBeliefSet beliefSet, IDesireSet<TBeliefSet> desireSet)
         {
             _beliefSet = beliefSet;
@@ -43,7 +44,7 @@ public BdiAgent(TBeliefSet beliefSet, IDesireSet<TBeliefSet> desireSet)
         /// Performs a single BDI cycle, in which the agent updates its beliefs, selects a concrete goal,
         /// chooses a concrete action to achieve the selected goal, and executes the chosen action.
         /// </summary>
-        /// <remarks>This method will get called every frame of the game.</remarks>
+        /// <remarks>This method will get called for every frame of the game.</remarks>
         public void Update()
         {
             // Belief

Aplib.Core/Agents/IAgent.cs

@@ -1,14 +1,14 @@
 namespace Aplib.Core.Agents
 {
     /// <summary>
-    /// Defines an agent that can play a game.
+    /// Defines a testing agent that can be updated for every frame of the game.
     /// </summary>
     public interface IAgent : ICompletable
     {
         /// <summary>
-        /// Updates the agent's state and goals.
+        /// Updates the agent's beliefs, desires, and intentions.
         /// </summary>
-        /// <remarks>This method will get called every frame of the game.</remarks>
+        /// <remarks>This method will get called for every frame of the game.</remarks>
         public void Update();
     }
 }

Aplib.Core/Belief/BeliefSets/BeliefSet.cs

@@ -4,21 +4,23 @@
 namespace Aplib.Core.Belief.BeliefSets
 {
     /// <summary>
-    /// The <see cref="BeliefSet"/> class can be inherited to define a set of beliefs for an agent.
-    /// All <i>public fields</i> of type <see cref="IBelief"/> that are defined in the inheriting class
-    /// are automatically updated when calling <see cref="UpdateBeliefs"/>.
+    /// This class can be inherited to define a set of beliefs for an agent.
+    /// All <i>public fields</i> defined in the inheriting class that implement <see cref="IBelief" /> 
+    /// are automatically updated when calling <see cref="UpdateBeliefs" />.
     /// </summary>
     public abstract class BeliefSet : IBeliefSet
     {
         /// <summary>
-        /// An array storing all <i>public fields</i> of type <see cref="IBelief"/> that are defined in the inheriting class.
+        /// An array storing all <i>public fields</i> of type <see cref="IBelief" /> that are defined in the inheriting
+        /// class.
         /// </summary>
         private readonly IBelief[] _beliefs;
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="BeliefSet"/> class,
-        /// and stores all <i>public fields</i> of type <see cref="IBelief"/> (that have been defined in the inheriting class) in an array.
-        /// All public <see cref="IBelief"/> fields are then automatically updated when calling <see cref="UpdateBeliefs"/>.
+        /// Initializes a new instance of the <see cref="BeliefSet"/> class and stores all <i>public fields</i> defined
+        /// in the inheriting class that implement <see cref="IBelief" /> in an array.
+        /// All public <see cref="IBelief" /> fields are then automatically updated when calling
+        /// <see cref="UpdateBeliefs" />.
         /// </summary>
         protected BeliefSet()
         {
@@ -30,7 +32,8 @@ protected BeliefSet()
         }
 
         /// <summary>
-        /// Updates all objects of type <see cref="IBelief"/> that are defined as <i>public fields</i> in the inheriting class.
+        /// Updates all objects that implement <see cref="IBelief"/> and that are defined as <i>public fields</i> in the
+        /// inheriting class.
         /// </summary>
         public void UpdateBeliefs()
         {

Aplib.Core/Belief/BeliefSets/IBeliefSet.cs

@@ -1,7 +1,7 @@
 namespace Aplib.Core.Belief.BeliefSets
 {
     /// <summary>
-    /// A belief set defines beliefs for an agent.
+    /// A belief set defines the beliefs of an agent.
     /// </summary>
     public interface IBeliefSet
     {

Aplib.Core/Belief/Beliefs/Belief.cs

@@ -1,18 +1,17 @@
-using Aplib.Core;
-
-namespace Aplib.Core.Belief.Beliefs
+namespace Aplib.Core.Belief.Beliefs
 {
     /// <summary>
-    /// The <see cref="Belief{TReference, TObservation}"/> class represents the agent's belief of a single object.
+    /// Represents the agent's belief of a single object.
     /// Some <i>object reference</i> is used to generate/update an <i>observation</i>
-    /// (i.e., some piece of information of the game state as perceived by an agent).
+    /// (i.e., some information about the game state as perceived by an agent).
     /// </summary>
     /// <remarks>
-    /// It supports implicit conversion to <typeparamref name="TObservation"/>.
+    /// This class supports implicit conversion to <typeparamref name="TObservation" />.
     /// </remarks>
     /// <typeparam name="TReference">
-    /// The type of the object reference used to generate/update the observation. This <i>must</i> be a reference type,
-    /// be aware that this is not enforced by C# if <typeparamref name="TReference"/> is an interface.
+    /// The type of the object reference used to generate/update the observation.
+    /// This <i>must</i> be a reference type,
+    /// be aware that this is not enforced by the type checker if <typeparamref name="TReference" /> is an interface.
     /// </typeparam>
     /// <typeparam name="TObservation">The type of the observation that the belief represents.</typeparam>
     public class Belief<TReference, TObservation> : IBelief where TReference : class
@@ -42,31 +41,34 @@ public class Belief<TReference, TObservation> : IBelief where TReference : class
         public Metadata Metadata { get; }
 
         /// <summary>
-        /// The observation represented by the belief (i.e., some piece of information of the game state as perceived by an agent).
+        /// The observation represented by the belief
+        /// (i.e., some information about the game state as perceived by an agent).
         /// </summary>
         public TObservation Observation { get; protected set; }
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="Belief{TReference, TObservation}"/> class with an object
+        /// Initializes a new instance of the <see cref="Belief{TReference, TObservation}" /> class with an object
         /// reference, a function to generate/update the observation using the object reference,
-        /// and a condition on when the observation should be updated.
+        /// and optionally a condition on when the observation should be updated.
         /// </summary>
         /// <param name="metadata">
-        /// Metadata about this Belief, used to quickly display the goal in several contexts.
+        /// Optional metadata about this belief, used to quickly display the goal in several contexts.
+        /// If omitted, default metadata will be used.
         /// </param>
         /// <param name="reference">
         /// The object reference used to generate/update the observation. This <i>must</i> be a reference type, be aware
-        /// that this is not enforced by C# if <typeparamref name="TReference"/> is an interface.
+        /// that this is not enforced by the type checker if <typeparamref name="TReference"/> is an interface.
         /// </param>
         /// <param name="getObservationFromReference">
         /// A function that takes an object reference and generates/updates an observation.
         /// </param>
         /// <param name="shouldUpdate">
-        /// A condition on when the observation should be updated. Takes the object reference
-        /// of the belief as a parameter for the predicate.
+        /// An optional condition on when the observation should be updated.
+        /// Takes the object reference of the belief as a parameter for the predicate.
+        /// If omitted, the belief will always update.
         /// </param>
         /// <exception cref="System.ArgumentException">
-        /// Thrown when <paramref name="reference"/> is not a reference type.
+        /// Thrown when <paramref name="reference" /> is not a reference type.
         /// </exception>
         public Belief
         (
@@ -89,7 +91,7 @@ System.Predicate<TReference> shouldUpdate
         }
 
         /// <inheritdoc
-        ///     cref="Belief{TReference,TObservation}(Metadata,TReference,System.Func{TReference,TObservation},System.Predicate{TReference})"/>
+        ///     cref="Belief{TReference,TObservation}(Core.Metadata,TReference,System.Func{TReference,TObservation},System.Predicate{TReference})" />
         public Belief
         (
             TReference reference,
@@ -101,7 +103,7 @@ System.Predicate<TReference> shouldUpdate
         }
 
         /// <inheritdoc
-        ///     cref="Belief{TReference,TObservation}(Metadata,TReference,System.Func{TReference,TObservation},System.Predicate{TReference})" />
+        ///     cref="Belief{TReference,TObservation}(Core.Metadata,TReference,System.Func{TReference,TObservation},System.Predicate{TReference})" />
         public Belief
         (
             Metadata metadata,
@@ -120,15 +122,15 @@ public Belief(TReference reference, System.Func<TReference, TObservation> getObs
         }
 
         /// <summary>
-        /// Implicit conversion operator to allow a <see cref="Belief{TReference, TObservation}"/> object
-        /// to be used where a <typeparamref name="TObservation"/> is expected.
+        /// Implicit conversion operator to allow a <see cref="Belief{TReference, TObservation}" /> object
+        /// to be used where a <typeparamref name="TObservation" /> is expected.
         /// </summary>
-        /// <param name="belief">The <see cref="Belief{TReference, TObservation}"/> object to convert.</param>
+        /// <param name="belief">The <see cref="Belief{TReference, TObservation}" /> object to convert.</param>
         public static implicit operator TObservation(Belief<TReference, TObservation> belief) => belief.Observation;
 
         /// <summary>
-        /// Generates/updates the observation if the shouldUpdate condition is satisfied.
-        /// The observation is then updated by calling the getObservationFromReference function.
+        /// Generates/updates the observation if the <c>shouldUpdate</c> condition is satisfied.
+        /// The observation is then updated by calling the <c>getObservationFromReference</c> function.
         /// </summary>
         public virtual void UpdateBelief()
         {

Aplib.Core/Belief/Beliefs/IBelief.cs

@@ -1,12 +1,13 @@
 namespace Aplib.Core.Belief.Beliefs
 {
     /// <summary>
-    /// A belief represents/encapsulates an observation (i.e., piece of information of the game state as perceived by an agent).
+    /// A belief represents/encapsulates an observation,
+    /// i.e., information about the game state as perceived by an agent.
     /// </summary>
     public interface IBelief
     {
         /// <summary>
-        /// Updates the belief based on information of the game state.
+        /// Updates the belief based on information about the game state.
         /// </summary>
         void UpdateBelief();
     }

Aplib.Core/Combinators.cs

@@ -63,49 +63,50 @@ public static SequentialGoalStructure<TBeliefSet> Seq<TBeliefSet>(params IGoalSt
 
         /// <inheritdoc cref="RandomTactic{TBeliefSet}(IMetadata,System.Predicate{TBeliefSet},ITactic{TBeliefSet}[])" />
         public static RandomTactic<TBeliefSet> Random<TBeliefSet>
-            (IMetadata metadata, System.Predicate<TBeliefSet> guard, params ITactic<TBeliefSet>[] subTactics)
+            (IMetadata metadata, System.Predicate<TBeliefSet> guard, params ITactic<TBeliefSet>[] subtactics)
             where TBeliefSet : IBeliefSet =>
-            new(metadata, guard, subTactics);
+            new(metadata, guard, subtactics);
 
         /// <inheritdoc cref="RandomTactic{TBeliefSet}(System.Predicate{TBeliefSet},ITactic{TBeliefSet}[])" />
         public static RandomTactic<TBeliefSet> Random<TBeliefSet>
-            (System.Predicate<TBeliefSet> guard, params ITactic<TBeliefSet>[] subTactics)
+            (System.Predicate<TBeliefSet> guard, params ITactic<TBeliefSet>[] subtactics)
             where TBeliefSet : IBeliefSet =>
-            new(guard, subTactics);
+            new(guard, subtactics);
 
         /// <inheritdoc cref="RandomTactic{TBeliefSet}(IMetadata,ITactic{TBeliefSet}[])" />
         public static RandomTactic<TBeliefSet> Random<TBeliefSet>
-            (IMetadata metadata, params ITactic<TBeliefSet>[] subTactics)
+            (IMetadata metadata, params ITactic<TBeliefSet>[] subtactics)
             where TBeliefSet : IBeliefSet =>
-            new(metadata, subTactics);
+            new(metadata, subtactics);
 
         /// <inheritdoc cref="RandomTactic{TBeliefSet}(ITactic{TBeliefSet}[])" />
-        public static RandomTactic<TBeliefSet> Random<TBeliefSet>(params ITactic<TBeliefSet>[] subTactics)
+        public static RandomTactic<TBeliefSet> Random<TBeliefSet>(params ITactic<TBeliefSet>[] subtactics)
             where TBeliefSet : IBeliefSet =>
-            new(subTactics);
+            new(subtactics);
 
-        /// <inheritdoc cref="FirstOfTactic{TBeliefSet}(IMetadata,System.Predicate{TBeliefSet},ITactic{TBeliefSet}[])" />
+        /// <inheritdoc
+        ///     cref="FirstOfTactic{TBeliefSet}(IMetadata,System.Predicate{TBeliefSet},ITactic{TBeliefSet}[])" />
         public static FirstOfTactic<TBeliefSet> FirstOf<TBeliefSet>
-            (IMetadata metadata, System.Predicate<TBeliefSet> guard, params ITactic<TBeliefSet>[] subTactics)
+            (IMetadata metadata, System.Predicate<TBeliefSet> guard, params ITactic<TBeliefSet>[] subtactics)
             where TBeliefSet : IBeliefSet =>
-            new(metadata, guard, subTactics);
+            new(metadata, guard, subtactics);
 
         /// <inheritdoc cref="FirstOfTactic{TBeliefSet}(System.Predicate{TBeliefSet},ITactic{TBeliefSet}[])" />
         public static FirstOfTactic<TBeliefSet> FirstOf<TBeliefSet>
-            (System.Predicate<TBeliefSet> guard, params ITactic<TBeliefSet>[] subTactics)
+            (System.Predicate<TBeliefSet> guard, params ITactic<TBeliefSet>[] subtactics)
             where TBeliefSet : IBeliefSet =>
-            new(guard, subTactics);
+            new(guard, subtactics);
 
         /// <inheritdoc cref="FirstOfTactic{TBeliefSet}(IMetadata,ITactic{TBeliefSet}[])"/>
         public static FirstOfTactic<TBeliefSet> FirstOf<TBeliefSet>
-            (IMetadata metadata, params ITactic<TBeliefSet>[] subTactics)
+            (IMetadata metadata, params ITactic<TBeliefSet>[] subtactics)
             where TBeliefSet : IBeliefSet =>
-            new(metadata, subTactics);
+            new(metadata, subtactics);
 
         /// <inheritdoc cref="FirstOfTactic{TBeliefSet}(ITactic{TBeliefSet}[])"/>
-        public static FirstOfTactic<TBeliefSet> FirstOf<TBeliefSet>(params ITactic<TBeliefSet>[] subTactics)
+        public static FirstOfTactic<TBeliefSet> FirstOf<TBeliefSet>(params ITactic<TBeliefSet>[] subtactics)
             where TBeliefSet : IBeliefSet =>
-            new(subTactics);
+            new(subtactics);
 
         /// <inheritdoc cref="PrimitiveTactic{TBeliefSet}(IMetadata,IAction{TBeliefSet},System.Predicate{TBeliefSet})"/>
         public static PrimitiveTactic<TBeliefSet> Primitive<TBeliefSet>
@@ -132,25 +133,26 @@ public static PrimitiveTactic<TBeliefSet> Primitive<TBeliefSet>(IAction<TBeliefS
         /// <inheritdoc
         ///     cref="PrimitiveTactic{TBeliefSet}(IMetadata,IQueryable{TBeliefSet},System.Predicate{TBeliefSet})"/>
         public static PrimitiveTactic<TBeliefSet> Primitive<TBeliefSet>
-            (IMetadata metadata, IQueryable<TBeliefSet> query, System.Predicate<TBeliefSet> guard)
+            (IMetadata metadata, IQueryable<TBeliefSet> queryAction, System.Predicate<TBeliefSet> guard)
             where TBeliefSet : IBeliefSet =>
-            new(metadata, query, guard);
+            new(metadata, queryAction, guard);
 
         /// <inheritdoc cref="PrimitiveTactic{TBeliefSet}(IQueryable{TBeliefSet},System.Predicate{TBeliefSet})"/>
         public static PrimitiveTactic<TBeliefSet> Primitive<TBeliefSet>
-            (IQueryable<TBeliefSet> query, System.Predicate<TBeliefSet> guard)
+            (IQueryable<TBeliefSet> queryAction, System.Predicate<TBeliefSet> guard)
             where TBeliefSet : IBeliefSet =>
-            new(query, guard);
+            new(queryAction, guard);
 
         /// <inheritdoc cref="PrimitiveTactic{TBeliefSet}(IMetadata,IQueryable{TBeliefSet})"/>
-        public static PrimitiveTactic<TBeliefSet> Primitive<TBeliefSet>(IMetadata metadata, IQueryable<TBeliefSet> query)
+        public static PrimitiveTactic<TBeliefSet> Primitive<TBeliefSet>
+            (IMetadata metadata, IQueryable<TBeliefSet> queryAction)
             where TBeliefSet : IBeliefSet =>
-            new(metadata, query);
+            new(metadata, queryAction);
 
         /// <inheritdoc cref="PrimitiveTactic{TBeliefSet}(IQueryable{TBeliefSet})"/>
-        public static PrimitiveTactic<TBeliefSet> Primitive<TBeliefSet>(IQueryable<TBeliefSet> query)
+        public static PrimitiveTactic<TBeliefSet> Primitive<TBeliefSet>(IQueryable<TBeliefSet> queryAction)
             where TBeliefSet : IBeliefSet =>
-            new(query);
+            new(queryAction);
 
         #endregion
     }

Aplib.Core/CompletionStatus.cs

@@ -6,18 +6,18 @@
     public enum CompletionStatus
     {
         /// <summary>
-        /// Represents the status of a completable object that is not yet completed.
+        /// The status of a completable object that is not yet completed.
         /// </summary>
         Unfinished,
 
         /// <summary>
-        /// Represents the status of a completable object that has been successfully completed.
+        /// The status of a completable object that has been successfully completed.
         /// </summary>
         Success,
 
         /// <summary>
-        /// Represents the status of a completable object that has failed to complete.
+        /// The status of a completable object that has failed to complete.
         /// </summary>
-        Failure
+        Failure,
     }
 }

Aplib.Core/ICompletable.cs

@@ -6,7 +6,7 @@
     public interface ICompletable
     {
         /// <summary>
-        /// Gets the completion status of the object.
+        /// Gets the completion status of the instance.
         /// </summary>
         public CompletionStatus Status { get; }
     }

Aplib.Core/IDocumented.cs

@@ -1,16 +1,13 @@
 namespace Aplib.Core
 {
     /// <summary>
-    /// Represents an object that contains general information on an instance, such as <see cref="IMetadata"/>.
+    /// Represents an object that contains general information on an instance, such as <see cref="IMetadata" />.
     /// </summary>
     public interface IDocumented
     {
         /// <summary>
-        /// Gets the metadata of the instance.
+        /// Gets the metadata of the instance. This metadata may be useful for debugging or logging.
         /// </summary>
-        /// <remark>
-        /// This metadata may be useful for debugging or logging.
-        /// </remark>
         public IMetadata Metadata { get; }
     }
 }

Aplib.Core/IMetadata.cs

@@ -2,11 +2,9 @@ namespace Aplib.Core
 {
     /// <summary>
     /// A collection of generic metadata for unique instances which should help
-    /// visualise the instance with human-readable information.
-    /// </summary>
-    /// <remark>
+    /// visualize the instance with human-readable information.
     /// This metadata may be useful for debugging or logging.
-    /// </remark>
+    /// </summary>
     public interface IMetadata
     {
         /// <summary>