From 828a83b91f2a7474d5df0372e444c7feb67ff2d3 Mon Sep 17 00:00:00 2001
From: guille <guillermopolito@gmail.com>
Date: Fri, 28 Oct 2016 11:39:59 +0200
Subject: [PATCH] Scaladocs for [[NeuronEntityRef]]s
---
.../n2s3/features/builder/ConnectionRef.scala | 6 ++++++
.../features/builder/InputNeuronGroupRef.scala | 2 +-
.../emeraude/n2s3/features/builder/N2S3.scala | 4 ++--
...{N2S3ActorRef.scala => NetworkEntityRef.scala} | 15 ++++++++++++---
.../features/builder/NeuronGroupObserverRef.scala | 2 +-
.../n2s3/features/builder/NeuronGroupRef.scala | 2 +-
.../n2s3/features/builder/NeuronRef.scala | 6 ++++--
.../features/builder/SynchronizedNeuronRef.scala | 6 ++++--
8 files changed, 31 insertions(+), 12 deletions(-)
rename n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/{N2S3ActorRef.scala => NetworkEntityRef.scala} (59%)
diff --git a/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/ConnectionRef.scala b/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/ConnectionRef.scala
index 7c8dbfef..5000ac94 100644
--- a/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/ConnectionRef.scala
+++ b/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/ConnectionRef.scala
@@ -2,6 +2,12 @@ package fr.univ_lille.cristal.emeraude.n2s3.features.builder
import fr.univ_lille.cristal.emeraude.n2s3.features.builder.connection.{ConnectionSet, ExternalConnectionPolicy}
+/**
+ * Models a connection between two neuron groups.
+ * @param from [[NeuronGroupRef]] origin of the connection
+ * @param to [[NeuronGroupRef]] destination of the connection
+ * @param connectionType the kind of connection used
+ */
class ConnectionRef(from: NeuronGroupRef, to: NeuronGroupRef, connectionType: ExternalConnectionPolicy) {
var deployed = false
diff --git a/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/InputNeuronGroupRef.scala b/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/InputNeuronGroupRef.scala
index 964ecfdb..c99ece57 100644
--- a/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/InputNeuronGroupRef.scala
+++ b/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/InputNeuronGroupRef.scala
@@ -8,7 +8,7 @@ import fr.univ_lille.cristal.emeraude.n2s3.support.io.{Input, InputSeq, N2S3Inpu
/**
- * An [[InputNeuronGroupRef]] is a [[NeuronGroupRef]] that includes input neurons and is bound to a stream of data.
+ * [[NeuronGroupRef]] that includes input neurons and is bound to a stream of data.
* This input neuron group contains as many neurons as the dimension of the input. I.e. if the input has a dimension of 748 bits, then the input neuron group will contain 748 neurons.
* Each of the input neurons can be connected to neurons of another neuron group.
*
diff --git a/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/N2S3.scala b/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/N2S3.scala
index 76e906b0..822a255b 100644
--- a/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/N2S3.scala
+++ b/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/N2S3.scala
@@ -14,8 +14,8 @@ import fr.univ_lille.cristal.emeraude.n2s3.support.actors.{Message, _}
import fr.univ_lille.cristal.emeraude.n2s3.support.io.{Input, InputSeq, N2S3Input}
/**
- * Main Simulator class.
- * An instance of N2S3 represents a simulation. A simulation is built by adding neuron groups to it, making connections between them and then observing the neuron using specific observers.
+ * Main Simulation class.
+ * Represents a simulation. A simulation is built by adding neuron groups to it, making connections between them and then observing the neuron using specific observers.
*
* N2S3's API hides the usage of actors to the end-user. It provides specific reference objects. These reference objects provide a clean, typed and synchronous API to interact with the underlying system.
*
diff --git a/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/N2S3ActorRef.scala b/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/NetworkEntityRef.scala
similarity index 59%
rename from n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/N2S3ActorRef.scala
rename to n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/NetworkEntityRef.scala
index 0b597156..8e5e2455 100644
--- a/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/N2S3ActorRef.scala
+++ b/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/NetworkEntityRef.scala
@@ -3,21 +3,30 @@ import fr.univ_lille.cristal.emeraude.n2s3.core.{ExternalSender, NetworkEntityPa
import fr.univ_lille.cristal.emeraude.n2s3.support.actors.Message
/**
- * Created by guille on 8/4/16.
+ * Reference to an network entity.
+ * It contains a [[NetworkEntityPath]] to the referenced entity and provides facility methods to communicate with it.
*/
-trait N2S3ActorRef {
+trait NetworkEntityRef {
var actorPath: Option[NetworkEntityPath] = None
def setActor(path: NetworkEntityPath) = this.actorPath = Some(path)
def getNetworkAddress = this.actorPath.get
-
+ /**
+ * Returns a boolean that indicates wether the actor of this ref is already deployed
+ */
def isDeployed = this.actorPath.nonEmpty
+ /**
+ * Sends a message to the entity without waiting for an answer
+ */
def send(message: Message): Unit = {
ExternalSender.sendTo(this.actorPath.get, message )
}
+ /**
+ * Sends a message to the entity and waits for it to answer
+ */
def ask(message: Message): Unit = {
ExternalSender.askTo(this.actorPath.get, message )
}
diff --git a/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/NeuronGroupObserverRef.scala b/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/NeuronGroupObserverRef.scala
index 0b4971db..c2f9e24e 100644
--- a/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/NeuronGroupObserverRef.scala
+++ b/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/NeuronGroupObserverRef.scala
@@ -3,7 +3,7 @@ package fr.univ_lille.cristal.emeraude.n2s3.features.builder
import akka.actor.ActorRef
/**
- * Created by guille on 6/2/16.
+ * A reference to a neuron group observer
*/
abstract class NeuronGroupObserverRef {
var deployed: Boolean = false
diff --git a/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/NeuronGroupRef.scala b/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/NeuronGroupRef.scala
index 8473fb1e..47604935 100644
--- a/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/NeuronGroupRef.scala
+++ b/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/NeuronGroupRef.scala
@@ -14,7 +14,7 @@ import scala.collection.mutable.ArrayBuffer
/**
* Created by guille on 6/2/16.
*/
-class NeuronGroupRef(n2s3: N2S3) extends N2S3ActorRef {
+class NeuronGroupRef(n2s3: N2S3) extends NetworkEntityRef {
var identifier: String = ""
diff --git a/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/NeuronRef.scala b/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/NeuronRef.scala
index 8f8094ee..f786a1d6 100644
--- a/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/NeuronRef.scala
+++ b/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/NeuronRef.scala
@@ -3,9 +3,11 @@ package fr.univ_lille.cristal.emeraude.n2s3.features.builder
import fr.univ_lille.cristal.emeraude.n2s3.core._
/**
- * Created by guille on 7/29/16.
+ * [[NetworkEntityRef]] that refers to a neuron inside the simulation
+ * @param group a ref to the neuron group that contains the neuron
+ * @param index the index of the neuron in [[group]]
*/
-class NeuronRef(val group: NeuronGroupRef, val index: Int) extends N2S3ActorRef {
+class NeuronRef(val group: NeuronGroupRef, val index: Int) extends NetworkEntityRef {
def getIdentifier: Any = this.group.getIdentifierOf(this)
def newNeuron(): NetworkEntity = group.defaultNeuronConstructor()
def isConnectedTo(aNeuron: NeuronRef) = group.isConnected(this, aNeuron)
diff --git a/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/SynchronizedNeuronRef.scala b/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/SynchronizedNeuronRef.scala
index 0c9f4ca3..3d28c547 100644
--- a/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/SynchronizedNeuronRef.scala
+++ b/n2s3/src/main/scala/fr/univ_lille/cristal/emeraude/n2s3/features/builder/SynchronizedNeuronRef.scala
@@ -6,9 +6,11 @@ import fr.univ_lille.cristal.emeraude.n2s3.core._
import fr.univ_lille.cristal.emeraude.n2s3.support.actors.Message
/**
- * Created by guille on 8/5/16.
+ * [[NetworkEntityRef]] that goes always through the synchronizer.
+ * @param synchronizerActor the synchronizer actor ref to pass by
+ * @param neuronRef the neuron ref that is being targetted
*/
-class SynchronizedNeuronRef(synchronizerActor: ActorRef, neuronRef: NeuronRef) extends N2S3ActorRef {
+class SynchronizedNeuronRef(synchronizerActor: ActorRef, neuronRef: NeuronRef) extends NetworkEntityRef {
this.setActor(NetworkEntityPath(synchronizerActor))
--
GitLab