chore(api-deps)!: update the infrastructure to Kotlin 2.3.10

alchemist-api/src/main/kotlin/it/unibo/alchemist/model/Actionable.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2010-2022, Danilo Pianini and contributors
+ * Copyright (C) 2010-2026, Danilo Pianini and contributors
  * listed, for each module, in the respective subproject's build.gradle.kts file.
  *
  * This file is part of Alchemist, and is distributed under the terms of the
@@ -91,12 +91,12 @@ sealed interface Actionable<T> :
     /**
      * Updates the scheduling of this reaction.
      *
-     * @param hasBeenExecuted
-     * true if the reaction have just been executed.
      * @param currentTime
      * the current [Time] of execution. This is mandatory in
      * order to correctly compute the time shift of an
      * already-scheduled reaction
+     * @param hasBeenExecuted
+     * true if the reaction have just been executed.
      * @param environment
      * the current environment
      */

alchemist-api/src/main/kotlin/it/unibo/alchemist/model/Node.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2010-2023, Danilo Pianini and contributors
+ * Copyright (C) 2010-2026, Danilo Pianini and contributors
  * listed, for each module, in the respective subproject's build.gradle.kts file.
  *
  * This file is part of Alchemist, and is distributed under the terms of the
@@ -188,16 +188,19 @@ interface Node<T> :
      */
     companion object {
         /**
-         * returns a [NodeProperty] of the provided type [C].
-         * @param [C] type of capability
-         * @return a capability of the provided type [C]
+         * Returns the node property of the reified type [C].
+         *
+         * @receiver the node from which to retrieve the property.
+         * @return the property of type [C].
+         * @throws IllegalArgumentException if no compatible property is present.
          */
         inline fun <T, reified C : NodeProperty<T>> Node<T>.asProperty(): C = asProperty(C::class)
 
         /**
-         * returns a [NodeProperty] of the provided type [C] or null if the node does not have a compatible property.
-         * @param [C] type of capability
-         * @return if present, a capability of the provided type [C]
+         * Returns the node property of the reified type [C], or null if the node does not have a compatible property.
+         *
+         * @receiver the node from which to retrieve the property.
+         * @return the property of type [C] if present, or null otherwise.
          */
         inline fun <T, reified C : NodeProperty<T>> Node<T>.asPropertyOrNull(): C? = when {
             properties.size <= 1 -> properties.firstOrNull() as? C

alchemist-cognitive-agents/src/main/kotlin/it/unibo/alchemist/model/cognitive/CognitiveModel.kt

@@ -10,36 +10,51 @@
 package it.unibo.alchemist.model.cognitive
 
 /**
- * Theoretical model to describe the cognitive processes underlying in an agent.
+ * Theoretical model that describes the cognitive processes of an agent.
+ *
+ * Implementations provide measures for the agent's belief about danger, fear level,
+ * and competing intentions to escape or remain.
  */
 interface CognitiveModel {
     /**
-     * Value representing the current belief of the situation dangerousness.
+     * Returns the agent's current belief about the situation's dangerousness.
+     *
+     * @return the perceived level of dangerousness as a [Double].
      */
     fun dangerBelief(): Double
 
     /**
-     * Value representing the level of fear.
+     * Returns the agent's current fear level.
+     *
+     * @return the fear level as a [Double].
      */
     fun fear(): Double
 
     /**
-     * Value representing the intention to escape. Opposed to [remainIntention].
+     * Returns the agent's intention to escape. This value is opposed to [remainIntention].
+     *
+     * @return the intention to escape as a [Double].
      */
     fun escapeIntention(): Double
 
     /**
-     * Value representing the intention to remain. Opposed to [escapeIntention]
+     * Returns the agent's intention to remain. This value is opposed to [escapeIntention].
+     *
+     * @return the intention to remain as a [Double].
      */
     fun remainIntention(): Double
 
     /**
-     * Update the current intensity of the aforementioned feelings considering a [frequency].
+     * Update the model internal state using the provided update frequency.
+     *
+     * @param frequency the update frequency (time between updates or update rate), represented as a [Double].
      */
     fun update(frequency: Double)
 
     /**
-     * Whether or not this node intends to escape.
+     * Whether the agent currently intends to escape.
+     *
+     * @return true if the escape intention is greater than the remain intention; false otherwise.
      */
     fun wantsToEscape(): Boolean = escapeIntention() > remainIntention()
 }

alchemist-cognitive-agents/src/main/kotlin/it/unibo/alchemist/model/cognitive/CognitiveProperty.kt

@@ -15,11 +15,13 @@ import it.unibo.alchemist.model.Node.Companion.asPropertyOrNull
 import it.unibo.alchemist.model.NodeProperty
 
 /**
- * The pedestrian's cognitive capability.
+ * Cognitive capability attached to a node.
+ *
+ * @param T the concentration type of the environment.
  */
 interface CognitiveProperty<T> : NodeProperty<T> {
     /**
-     * The molecule associated with danger in the environment.
+     * The molecule used to signal danger in the environment, if any.
      */
     val danger: Molecule?
 
@@ -29,7 +31,9 @@ interface CognitiveProperty<T> : NodeProperty<T> {
     val cognitiveModel: CognitiveModel
 
     /**
-     * The mind model of all people considered influential for this cognitive pedestrian.
+     * The cognitive models of people considered influential for this pedestrian.
+     *
+     * @return a list of [CognitiveModel] instances representing influential people.
      */
     fun influentialPeople(): List<CognitiveModel> = node
         .asProperty<T, PerceptiveProperty<T>>()

alchemist-cognitive-agents/src/main/kotlin/it/unibo/alchemist/model/cognitive/Group.kt

@@ -3,11 +3,15 @@ package it.unibo.alchemist.model.cognitive
 import it.unibo.alchemist.model.Node
 
 /**
- * A group of nodes.
+ * Represents a group of nodes (pedestrians) that can be treated collectively.
+ *
+ * @param T the concentration type used by nodes in the group.
  */
 interface Group<T> : MutableList<Node<T>> {
     /**
-     * The list of pedestrians belonging to this group.
+     * The list of nodes that belong to this group.
+     *
+     * @return a [List] of [Node] instances representing the group's members.
      */
     val members: List<Node<T>> get() = this
 }

alchemist-cognitive-agents/src/main/kotlin/it/unibo/alchemist/model/cognitive/GroupSteeringAction.kt

@@ -14,11 +14,16 @@ import it.unibo.alchemist.model.Position
 import it.unibo.alchemist.model.geometry.Vector
 
 /**
- * A [SteeringAction] related to a group of pedestrians.
+ * A [SteeringAction] that is influenced by a group of pedestrians.
+ *
+ * @param T the concentration type.
+ * @param P the position/vector type used by the steering action.
  */
 interface GroupSteeringAction<T, P> : SteeringAction<T, P> where P : Position<P>, P : Vector<P> {
     /**
-     * The list of pedestrians influencing this action.
+     * Returns the list of nodes (pedestrians) that influence this group steering action.
+     *
+     * @return a [List] of [Node] instances representing the influencing group.
      */
     fun group(): List<Node<T>>
 }

alchemist-cognitive-agents/src/main/kotlin/it/unibo/alchemist/model/cognitive/GroupWithLeader.kt

@@ -12,11 +12,14 @@ package it.unibo.alchemist.model.cognitive
 import it.unibo.alchemist.model.Node
 
 /**
- * A group with a special member acting as a leader.
+ * A group that designates a special member as the leader.
+ *
+ * @param T the concentration type.
+ * @param N the concrete node type used for the leader.
  */
 interface GroupWithLeader<T, N : Node<T>> : Group<T> {
     /**
-     * The leader of the group.
+     * The node acting as the group's leader.
      */
     val leader: N
 }

alchemist-cognitive-agents/src/main/kotlin/it/unibo/alchemist/model/cognitive/HeterogeneousPedestrianModel.kt

@@ -18,34 +18,32 @@ import it.unibo.alchemist.model.geometry.Transformation
 import it.unibo.alchemist.model.geometry.Vector
 
 /**
- * A pedestrian with individual characteristics.
+ * Model of a pedestrian with heterogeneous individual characteristics.
+ *
+ * @param T the concentration type.
+ * @param S the concrete Vector type used for geometry operations.
+ * @param A the concrete Transformation type compatible with [S].
  */
 data class HeterogeneousPedestrianModel<T, S : Vector<S>, A : Transformation<S>>(
-    /**
-     * The age of this pedestrian.
-     */
+    /** The age of this pedestrian. */
     val age: Age,
-    /**
-     * The gender of this pedestrian.
-     */
+    /** The gender of this pedestrian. */
     val gender: Gender,
-    /**
-     * The speed of an agent considering its age, gender and a random factor.
-     */
+    /** The agent's speed considering age, gender and randomness. */
     val speed: Speed,
     /**
-     * Value between 0 and 1 representing the attitude towards conforming to social rules of this pedestrian.
+     * Value between 0 and 1 representing the attitude toward conforming to social rules.
      */
     val compliance: Double = Compliance(age, gender).level,
-    /**
-     * The attitude of an agent towards helping another agent.
-     */
+    /** The attitude toward helping other agents. */
     val helpAttitude: HelpAttitude = HelpAttitude(age, gender),
 ) {
     /**
-     * Value between 0 and 1 representing the probability this pedestrian will help another pedestrian in difficulty.
+     * Returns the probability that this pedestrian will help another pedestrian.
      *
-     * @param toHelp The pedestrian who needs help.
+     * @param toHelp the pedestrian who may receive help.
+     * @param isGroupMember true if the pedestrian in difficulty is a member of the helper's group.
+     * @return a probability in [0.0, 1.0] representing the likelihood of offering help.
      */
     fun probabilityOfHelping(toHelp: HeterogeneousPedestrianModel<T, S, A>, isGroupMember: Boolean): Double =
         helpAttitude.level(toHelp.age, toHelp.gender, isGroupMember)

alchemist-cognitive-agents/src/main/kotlin/it/unibo/alchemist/model/cognitive/Human2DProperty.kt

@@ -14,5 +14,7 @@ import it.unibo.alchemist.model.positions.Euclidean2DPosition
 
 /**
  * A capability representing a pedestrian's individual characteristics in a 2D space.
+ *
+ * @param T the concentration type.
  */
 typealias Human2DProperty<T> = HumanProperty<T, Euclidean2DPosition, Euclidean2DTransformation>

alchemist-cognitive-agents/src/main/kotlin/it/unibo/alchemist/model/cognitive/HumanProperty.kt

@@ -18,38 +18,36 @@ import it.unibo.alchemist.model.geometry.Transformation
 import it.unibo.alchemist.model.geometry.Vector
 
 /**
- * A capability representing a pedestrian's individual characteristics.
+ * Capability representing a pedestrian's individual characteristics.
+ *
+ * @param T the concentration type.
+ * @param S the concrete Vector type used for geometry operations.
+ * @param A the concrete Transformation type compatible with [S].
  */
 interface HumanProperty<T, S : Vector<S>, A : Transformation<S>> : NodeProperty<T> {
-    /**
-     * The age of this pedestrian.
-     */
+    /** The age of this pedestrian. */
     val age: Age
 
-    /**
-     * The gender of this pedestrian.
-     */
+    /** The gender of this pedestrian. */
     val gender: Gender
 
-    /**
-     * The speed of an agent considering its age, gender and a random factor.
-     */
+    /** The agent's speed considering age, gender and randomness. */
     val speed: Speed
 
     /**
-     * Value between 0 and 1 representing the attitude towards conforming to social rules of this pedestrian.
+     * Value between 0 and 1 representing the attitude toward conforming to social rules.
      */
     val compliance: Double
 
-    /**
-     * The attitude of an agent towards helping another agent.
-     */
+    /** The attitude toward helping other agents. */
     val helpAttitude: HelpAttitude
 
     /**
-     * Value between 0 and 1 representing the probability this pedestrian will help another pedestrian in difficulty.
+     * Returns the probability that this pedestrian will help another pedestrian.
      *
-     * @param toHelp The pedestrian who needs help.
+     * @param toHelp the pedestrian who may receive help.
+     * @param isGroupMember true if the pedestrian in difficulty is a member of the helper's group.
+     * @return a probability in [0.0, 1.0] representing the likelihood of offering help.
      */
     fun probabilityOfHelping(toHelp: HeterogeneousPedestrianModel<T, S, A>, isGroupMember: Boolean): Double =
         helpAttitude.level(toHelp.age, toHelp.gender, isGroupMember)

alchemist-cognitive-agents/src/main/kotlin/it/unibo/alchemist/model/cognitive/NavigationAction.kt

@@ -18,65 +18,60 @@ import it.unibo.alchemist.model.geometry.Transformation
 import it.unibo.alchemist.model.geometry.Vector
 
 /**
- * A [SteeringAction] allowing a node to navigate an environment consciously (e.g. without getting stuck in
- * U-shaped obstacles). Names are inspired to indoor environments, but this interface works for outdoor ones as well.
+ * A [SteeringAction] allowing a node to navigate an environment consciously (for example, avoiding
+ * getting stuck in U-shaped obstacles). Names are inspired by indoor environments, but this
+ * interface also works for outdoor scenarios.
  *
  * @param T the concentration type.
- * @param P the [Position] type and [Vector] type for the space the node is into.
- * @param A the transformations supported by the shapes in this space.
- * @param L the type of landmarks of the node's cognitive map.
- * @param R the type of edges of the node's cognitive map, representing the [R]elations between landmarks.
- * @param N the type of nodes of the navigation graph provided by the [environment].
- * @param E the type of edges of the navigation graph provided by the [environment].
+ * @param P the [Position] and [Vector] type used by the space the node occupies.
+ * @param A the transformation type supported by the shapes in this space.
+ * @param L the type of landmarks in the node's cognitive map.
+ * @param R the type of edges in the node's cognitive map, representing relations between landmarks.
+ * @param N the type of navigation-area shapes provided by the [environment].
+ * @param E the type of edges (passages) of the navigation graph provided by the [environment].
  */
 interface NavigationAction<T, P, A, L, R, N, E> :
     SteeringAction<T, P>
     where P : Position<P>, P : Vector<P>,
           A : Transformation<P>,
           L : ConvexShape<P, A>,
           N : ConvexShape<P, A> {
-    /**
-     * The owner of this action.
-     */
+    /** The owner of this action. */
     val navigatingNode: Node<T>
 
-    /**
-     * The [navigatingNode]'s orientingProperty.
-     */
+    /** The [navigatingNode]'s orienting property. */
     val orientingProperty get() = navigatingNode.asProperty<T, OrientingProperty<T, P, A, L, N, E>>()
 
-    /**
-     * The environment the [navigatingNode] is into.
-     */
+    /** The environment the [navigatingNode] is in. */
     val environment: EnvironmentWithGraph<*, T, P, A, N, E>
 
-    /**
-     * The position of the [navigatingNode] in the [environment].
-     */
+    /** The position of the [navigatingNode] in the [environment]. */
     val pedestrianPosition: P
 
-    /**
-     * The room (= environment's area) the [navigatingNode] is into.
-     */
+    /** The room (environment area) the [navigatingNode] is in, if any. */
     val currentRoom: N?
 
     /**
-     * @returns the doors (= passages/edges) the node can perceive.
+     * Returns the doors (passages/edges) the node can perceive.
+     *
+     * @return a [List] of visible door edges of type [E].
      */
     fun doorsInSight(): List<E>
 
     /**
-     * Moves the node across the provided [door], which must be among [doorsInSight].
+     * Moves the node across the provided [door], which must be among the doors returned by [doorsInSight].
+     *
+     * @param door the door (edge) to cross.
      */
     fun crossDoor(door: E)
 
     /**
      * Moves the node to the given final [destination], which must be inside [currentRoom].
+     *
+     * @param destination the final destination position inside the current room.
      */
     fun moveToFinal(destination: P)
 
-    /**
-     * Stops moving the node.
-     */
+    /** Stops the node by moving it to its current position. */
     fun stop() = moveToFinal(pedestrianPosition)
 }