From 45310801a826d84bca9378b6fbcb422997eb774a Mon Sep 17 00:00:00 2001
From: Andrea Burattin <andrea.burattin@gmail.com>
Date: Thu, 3 Mar 2022 15:21:43 +0100
Subject: [PATCH] Added documentation to code

---
 .gitignore                                    |  1 +
 .../filters/ExcludeActivitiesFilter.java      | 12 +++++
 .../ExcludeOnCaseAttributeEqualityFilter.java | 21 ++++++++
 ...ExcludeOnEventAttributeEqualityFilter.java | 21 ++++++++
 .../filters/RetainActivitiesFilter.java       | 12 +++++
 .../RetainOnCaseAttributeEqualityFilter.java  | 21 ++++++++
 .../RetainOnEventAttributeEqualityFilter.java | 21 ++++++++
 .../java/beamline/filters/package-info.java   |  5 ++
 .../mappers/DirectlyFollowsRelation.java      | 28 +++++++++++
 .../InfiniteSizeDirectlyFollowsMapper.java    | 12 +++++
 .../java/beamline/mappers/package-info.java   |  5 ++
 .../algorithms/HookEventProcessing.java       | 11 ++++
 .../algorithms/StreamMiningAlgorithm.java     | 50 +++++++++++++++++--
 .../models/algorithms/package-info.java       |  5 ++
 .../models/responses/GraphvizResponse.java    | 11 ++++
 .../beamline/models/responses/Response.java   |  5 ++
 .../models/responses/package-info.java        |  5 ++
 .../java/beamline/sources/CSVLogSource.java   | 36 +++++++++++++
 .../java/beamline/sources/MQTTXesSource.java  | 21 ++++++++
 src/main/java/beamline/sources/Source.java    | 23 +++++++++
 .../java/beamline/sources/XesLogSource.java   | 22 ++++++++
 src/main/java/beamline/sources/XesSource.java |  6 +++
 .../java/beamline/sources/package-info.java   |  6 +++
 23 files changed, 355 insertions(+), 5 deletions(-)
 create mode 100644 src/main/java/beamline/filters/package-info.java
 create mode 100644 src/main/java/beamline/mappers/package-info.java
 create mode 100644 src/main/java/beamline/models/algorithms/package-info.java
 create mode 100644 src/main/java/beamline/models/responses/package-info.java
 create mode 100644 src/main/java/beamline/sources/package-info.java

diff --git a/.gitignore b/.gitignore
index b83d222..35a4d80 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,2 @@
 /target/
+/doc/
diff --git a/src/main/java/beamline/filters/ExcludeActivitiesFilter.java b/src/main/java/beamline/filters/ExcludeActivitiesFilter.java
index abdabd4..4886ad0 100644
--- a/src/main/java/beamline/filters/ExcludeActivitiesFilter.java
+++ b/src/main/java/beamline/filters/ExcludeActivitiesFilter.java
@@ -4,8 +4,20 @@ import org.deckfour.xes.extension.std.XConceptExtension;
 import org.deckfour.xes.model.XAttributeLiteral;
 import org.deckfour.xes.model.impl.XAttributeLiteralImpl;
 
+/**
+ * A specific instance of the {@link ExcludeOnEventAttributeEqualityFilter} that
+ * considers the name of the activity as attribute to filter.
+ * 
+ * @author Andrea Burattin
+ *
+ */
 public class ExcludeActivitiesFilter extends ExcludeOnEventAttributeEqualityFilter<XAttributeLiteral> {
 
+	/**
+	 * Constructors
+	 * 
+	 * @param activities the sequence of activity names to exclude
+	 */
 	public ExcludeActivitiesFilter(String ...activities) {
 		super(XConceptExtension.KEY_NAME);
 		
diff --git a/src/main/java/beamline/filters/ExcludeOnCaseAttributeEqualityFilter.java b/src/main/java/beamline/filters/ExcludeOnCaseAttributeEqualityFilter.java
index 4c221c1..c3c62e1 100644
--- a/src/main/java/beamline/filters/ExcludeOnCaseAttributeEqualityFilter.java
+++ b/src/main/java/beamline/filters/ExcludeOnCaseAttributeEqualityFilter.java
@@ -10,17 +10,38 @@ import org.deckfour.xes.model.XTrace;
 import io.reactivex.rxjava3.annotations.NonNull;
 import io.reactivex.rxjava3.functions.Predicate;
 
+/**
+ * This filter excludes events based on the equality of a certain trace
+ * attribute to a given set of values. Values are considered in disjunction
+ * (i.e., it is enough that the attribute is equal to one of the values to
+ * discard the event).
+ * 
+ * @author Andrea Burattin
+ *
+ * @param <T> the type of the attribute
+ */
 public class ExcludeOnCaseAttributeEqualityFilter<T extends XAttribute> implements Predicate<XTrace> {
 
 	private String attributeName;
 	private Set<T> attributeValues;
 	
+	/**
+	 * Constructor
+	 * 
+	 * @param attributeName the name of the trace attribute
+	 * @param values the sequence of values to consider
+	 */
 	@SafeVarargs
 	public ExcludeOnCaseAttributeEqualityFilter(String attributeName, T ...values) {
 		this.attributeName = attributeName;
 		this.attributeValues = new HashSet<T>(Arrays.asList(values));
 	}
 	
+	/**
+	 * Adds the value to the list of values to be considered for removal
+	 * 
+	 * @param value
+	 */
 	public void addValue(T value) {
 		this.attributeValues.add(value);
 	}
diff --git a/src/main/java/beamline/filters/ExcludeOnEventAttributeEqualityFilter.java b/src/main/java/beamline/filters/ExcludeOnEventAttributeEqualityFilter.java
index 7e722ab..d43d575 100644
--- a/src/main/java/beamline/filters/ExcludeOnEventAttributeEqualityFilter.java
+++ b/src/main/java/beamline/filters/ExcludeOnEventAttributeEqualityFilter.java
@@ -10,17 +10,38 @@ import org.deckfour.xes.model.XTrace;
 import io.reactivex.rxjava3.annotations.NonNull;
 import io.reactivex.rxjava3.functions.Predicate;
 
+/**
+ * This filter excludes events based on the equality of a certain event
+ * attribute to a given set of values. Values are considered in disjunction
+ * (i.e., it is enough that the attribute is equal to one of the values to
+ * discard the event).
+ * 
+ * @author Andrea Burattin
+ *
+ * @param <T> the type of the attribute
+ */
 public class ExcludeOnEventAttributeEqualityFilter<T extends XAttribute> implements Predicate<XTrace> {
 
 	private String attributeName;
 	private Set<T> attributeValues;
 	
+	/**
+	 * Constructor
+	 * 
+	 * @param attributeName the name of the event attribute
+	 * @param values the sequence of values to consider
+	 */
 	@SafeVarargs
 	public ExcludeOnEventAttributeEqualityFilter(String attributeName, T ...values) {
 		this.attributeName = attributeName;
 		this.attributeValues = new HashSet<T>(Arrays.asList(values));
 	}
 	
+	/**
+	 * Adds the value to the list of values to be considered for removal
+	 * 
+	 * @param value
+	 */
 	public void addValue(T value) {
 		this.attributeValues.add(value);
 	}
diff --git a/src/main/java/beamline/filters/RetainActivitiesFilter.java b/src/main/java/beamline/filters/RetainActivitiesFilter.java
index 5676c1d..8e0a525 100644
--- a/src/main/java/beamline/filters/RetainActivitiesFilter.java
+++ b/src/main/java/beamline/filters/RetainActivitiesFilter.java
@@ -4,8 +4,20 @@ import org.deckfour.xes.extension.std.XConceptExtension;
 import org.deckfour.xes.model.XAttributeLiteral;
 import org.deckfour.xes.model.impl.XAttributeLiteralImpl;
 
+/**
+ * A specific instance of the {@link RetainOnEventAttributeEqualityFilter} that
+ * considers the name of the activity as attribute to filter.
+ * 
+ * @author Andrea Burattin
+ *
+ */
 public class RetainActivitiesFilter extends RetainOnEventAttributeEqualityFilter<XAttributeLiteral> {
 
+	/**
+	 * Constructors
+	 * 
+	 * @param activities the sequence of activity names to retain
+	 */
 	public RetainActivitiesFilter(String ...activities) {
 		super(XConceptExtension.KEY_NAME);
 		
diff --git a/src/main/java/beamline/filters/RetainOnCaseAttributeEqualityFilter.java b/src/main/java/beamline/filters/RetainOnCaseAttributeEqualityFilter.java
index 57a115c..68f2b9d 100644
--- a/src/main/java/beamline/filters/RetainOnCaseAttributeEqualityFilter.java
+++ b/src/main/java/beamline/filters/RetainOnCaseAttributeEqualityFilter.java
@@ -10,17 +10,38 @@ import org.deckfour.xes.model.XTrace;
 import io.reactivex.rxjava3.annotations.NonNull;
 import io.reactivex.rxjava3.functions.Predicate;
 
+/**
+ * This filter retains events based on the equality of a certain trace
+ * attribute to a given set of values. Values are considered in disjunction
+ * (i.e., it is enough that the attribute is equal to one of the values to
+ * retain the event).
+ * 
+ * @author Andrea Burattin
+ *
+ * @param <T> the type of the attribute
+ */
 public class RetainOnCaseAttributeEqualityFilter<T extends XAttribute> implements Predicate<XTrace> {
 
 	private String attributeName;
 	private Set<T> attributeValues;
 	
+	/**
+	 * Constructor
+	 * 
+	 * @param attributeName the name of the trace attribute
+	 * @param values the sequence of values to consider
+	 */
 	@SafeVarargs
 	public RetainOnCaseAttributeEqualityFilter(String attributeName, T ...values) {
 		this.attributeName = attributeName;
 		this.attributeValues = new HashSet<T>(Arrays.asList(values));
 	}
 	
+	/**
+	 * Adds the value to the list of values to be considered for retention
+	 * 
+	 * @param value
+	 */
 	public void addValue(T value) {
 		this.attributeValues.add(value);
 	}
diff --git a/src/main/java/beamline/filters/RetainOnEventAttributeEqualityFilter.java b/src/main/java/beamline/filters/RetainOnEventAttributeEqualityFilter.java
index 35ea4c3..4d2bf5b 100644
--- a/src/main/java/beamline/filters/RetainOnEventAttributeEqualityFilter.java
+++ b/src/main/java/beamline/filters/RetainOnEventAttributeEqualityFilter.java
@@ -10,17 +10,38 @@ import org.deckfour.xes.model.XTrace;
 import io.reactivex.rxjava3.annotations.NonNull;
 import io.reactivex.rxjava3.functions.Predicate;
 
+/**
+ * This filter retains events based on the equality of a certain event
+ * attribute to a given set of values. Values are considered in disjunction
+ * (i.e., it is enough that the attribute is equal to one of the values to
+ * retain the event).
+ * 
+ * @author Andrea Burattin
+ *
+ * @param <T> the type of the attribute
+ */
 public class RetainOnEventAttributeEqualityFilter<T extends XAttribute> implements Predicate<XTrace> {
 
 	private String attributeName;
 	private Set<T> attributeValues;
 	
+	/**
+	 * Constructor
+	 * 
+	 * @param attributeName the name of the event attribute
+	 * @param values the sequence of values to consider
+	 */
 	@SafeVarargs
 	public RetainOnEventAttributeEqualityFilter(String attributeName, T ...values) {
 		this.attributeName = attributeName;
 		this.attributeValues = new HashSet<T>(Arrays.asList(values));
 	}
 	
+	/**
+	 * Adds the value to the list of values to be considered for retention
+	 * 
+	 * @param value
+	 */
 	public void addValue(T value) {
 		this.attributeValues.add(value);
 	}
diff --git a/src/main/java/beamline/filters/package-info.java b/src/main/java/beamline/filters/package-info.java
new file mode 100644
index 0000000..f21d673
--- /dev/null
+++ b/src/main/java/beamline/filters/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * This package contains some filters that are available by default in the
+ * framework.
+ */
+package beamline.filters;
\ No newline at end of file
diff --git a/src/main/java/beamline/mappers/DirectlyFollowsRelation.java b/src/main/java/beamline/mappers/DirectlyFollowsRelation.java
index 333c6db..e619d6c 100644
--- a/src/main/java/beamline/mappers/DirectlyFollowsRelation.java
+++ b/src/main/java/beamline/mappers/DirectlyFollowsRelation.java
@@ -2,26 +2,54 @@ package beamline.mappers;
 
 import org.deckfour.xes.model.XEvent;
 
+/**
+ * This class represents a directly follows relation as produced by
+ * {@link InfiniteSizeDirectlyFollowsMapper}.
+ * 
+ * @author Andrea Burattin
+ */
 public class DirectlyFollowsRelation {
 
 	private String caseId;
 	public XEvent first;
 	public XEvent second;
 	
+	/**
+	 * Constructor
+	 * 
+	 * @param caseId
+	 * @param first
+	 * @param second
+	 */
 	public DirectlyFollowsRelation(String caseId, XEvent first, XEvent second) {
 		this.caseId = caseId;
 		this.first = first;
 		this.second = second;
 	}
 	
+	/**
+	 * Returns the case id this directly follows relation belongs to
+	 * 
+	 * @return
+	 */
 	public String getCaseId() {
 		return caseId;
 	}
 
+	/**
+	 * Returns the first event
+	 * 
+	 * @return
+	 */
 	public XEvent getFirst() {
 		return first;
 	}
 
+	/**
+	 * Returns the second event
+	 * 
+	 * @return
+	 */
 	public XEvent getSecond() {
 		return second;
 	}
diff --git a/src/main/java/beamline/mappers/InfiniteSizeDirectlyFollowsMapper.java b/src/main/java/beamline/mappers/InfiniteSizeDirectlyFollowsMapper.java
index a6c6dac..be6255a 100644
--- a/src/main/java/beamline/mappers/InfiniteSizeDirectlyFollowsMapper.java
+++ b/src/main/java/beamline/mappers/InfiniteSizeDirectlyFollowsMapper.java
@@ -12,6 +12,18 @@ import io.reactivex.rxjava3.core.Observable;
 import io.reactivex.rxjava3.core.ObservableSource;
 import io.reactivex.rxjava3.functions.Function;
 
+/**
+ * This mapper transforms a stream of {@link XTrace}s into a stream of
+ * {@link DirectlyFollowsRelation}s. It transforms each pair of consequent
+ * events appearing in the same case as a directly follows operator (generating
+ * an object with type {@link DirectlyFollowsRelation}).
+ * 
+ * <p>
+ * This mapper is called infinite because it's memory footprint will grow as the
+ * number of case ids grows as well.
+ * 
+ * @author Andrea Burattin
+ */
 public class InfiniteSizeDirectlyFollowsMapper implements Function<XTrace, ObservableSource<DirectlyFollowsRelation>> {
 
 	private Map<String, XEvent> map = new HashMap<String, XEvent>();
diff --git a/src/main/java/beamline/mappers/package-info.java b/src/main/java/beamline/mappers/package-info.java
new file mode 100644
index 0000000..9e81654
--- /dev/null
+++ b/src/main/java/beamline/mappers/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * This package contains some mappers that are available by default in the
+ * framework.
+ */
+package beamline.mappers;
\ No newline at end of file
diff --git a/src/main/java/beamline/models/algorithms/HookEventProcessing.java b/src/main/java/beamline/models/algorithms/HookEventProcessing.java
index 9477abb..590620e 100644
--- a/src/main/java/beamline/models/algorithms/HookEventProcessing.java
+++ b/src/main/java/beamline/models/algorithms/HookEventProcessing.java
@@ -1,6 +1,17 @@
 package beamline.models.algorithms;
 
+/**
+ * This interface defines the structure of the callback function that a
+ * {@link StreamMiningAlgorithm} can execute (cf.,
+ * {@link StreamMiningAlgorithm#setOnBeforeEvent(HookEventProcessing)} and
+ * {@link StreamMiningAlgorithm#setOnAfterEvent(HookEventProcessing)}).
+ * 
+ * @author Andrea Burattin
+ */
 public interface HookEventProcessing {
 
+	/**
+	 * The actual function to trigger
+	 */
 	public void trigger();
 }
diff --git a/src/main/java/beamline/models/algorithms/StreamMiningAlgorithm.java b/src/main/java/beamline/models/algorithms/StreamMiningAlgorithm.java
index a7cb2c7..95ece21 100644
--- a/src/main/java/beamline/models/algorithms/StreamMiningAlgorithm.java
+++ b/src/main/java/beamline/models/algorithms/StreamMiningAlgorithm.java
@@ -3,6 +3,16 @@ package beamline.models.algorithms;
 import io.reactivex.rxjava3.annotations.NonNull;
 import io.reactivex.rxjava3.functions.Consumer;
 
+/**
+ * This abstract class defines the root of the mining algorithms hierarchy. It
+ * is a {@link Consumer} of elements with type <tt>T</tt> that is capable of
+ * producing responses of a certain type <tt>K</tt>.
+ * 
+ * @author Andrea Burattin
+ *
+ * @param <T> the type of the consumed events
+ * @param <K> the type of the responses produced by the mining algorithm
+ */
 public abstract class StreamMiningAlgorithm<T, K> implements Consumer<T> {
 
 	private int processedEvents = 0;
@@ -10,29 +20,59 @@ public abstract class StreamMiningAlgorithm<T, K> implements Consumer<T> {
 	private HookEventProcessing onBeforeEvent = null;
 	private HookEventProcessing onAfterEvent = null;
 	
+	/**
+	 * This abstract method is what each derive class is expected to implement.
+	 * The argument of the method is the new observation and the returned value
+	 * is the result of the mining.
+	 * 
+	 * @param event the new event being observed
+	 * @return the result of the mining of the event
+	 */
 	public abstract K ingest(T event);
 	
-	public void process(T event) {
-		this.processedEvents++;
-		latestResponse = ingest(event);
-	}
-	
+	/**
+	 * Returns the total number of events processed so far
+	 * 
+	 * @return
+	 */
 	public int getProcessedEvents() {
 		return processedEvents;
 	}
 	
+	/**
+	 * Returns the latest result of the mining
+	 * 
+	 * @return
+	 */
 	public K getLatestResponse() {
 		return latestResponse;
 	}
 	
+	/**
+	 * This method can be used to set a hook to a callback function to be
+	 * executed before an event is processed
+	 * 
+	 * @param onBeforeEvent the callback function
+	 */
 	public void setOnBeforeEvent(HookEventProcessing onBeforeEvent) {
 		this.onBeforeEvent = onBeforeEvent;
 	}
 	
+	/**
+	 * This method can be used to set a hook to a callback function to be
+	 * executed after an event is processed
+	 * 
+	 * @param onAfterEvent the callback function
+	 */
 	public void setOnAfterEvent(HookEventProcessing onAfterEvent) {
 		this.onAfterEvent = onAfterEvent;
 	}
 	
+	protected void process(T event) {
+		this.processedEvents++;
+		latestResponse = ingest(event);
+	}
+	
 	protected K setLatestResponse(K latestResponse) {
 		this.latestResponse = latestResponse;
 		return latestResponse;
diff --git a/src/main/java/beamline/models/algorithms/package-info.java b/src/main/java/beamline/models/algorithms/package-info.java
new file mode 100644
index 0000000..adea8f8
--- /dev/null
+++ b/src/main/java/beamline/models/algorithms/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * This package contains all classes of the framework necessary to have mining
+ * algorithms functioning.
+ */
+package beamline.models.algorithms;
\ No newline at end of file
diff --git a/src/main/java/beamline/models/responses/GraphvizResponse.java b/src/main/java/beamline/models/responses/GraphvizResponse.java
index a638528..2405813 100644
--- a/src/main/java/beamline/models/responses/GraphvizResponse.java
+++ b/src/main/java/beamline/models/responses/GraphvizResponse.java
@@ -2,7 +2,18 @@ package beamline.models.responses;
 
 import beamline.graphviz.Dot;
 
+/**
+ * A refined {@link Response} that can be rendered in Graphviz using the Dot
+ * language.
+ * 
+ * @author Andrea Burattin
+ */
 public interface GraphvizResponse extends Response {
 
+	/**
+	 * Returns the Dot representation of the response
+	 * 
+	 * @return
+	 */
 	public abstract Dot generateDot();
 }
diff --git a/src/main/java/beamline/models/responses/Response.java b/src/main/java/beamline/models/responses/Response.java
index aadfed5..c728c69 100644
--- a/src/main/java/beamline/models/responses/Response.java
+++ b/src/main/java/beamline/models/responses/Response.java
@@ -1,5 +1,10 @@
 package beamline.models.responses;
 
+/**
+ * Marker interface used to define the type of the responses
+ * 
+ * @author Andrea Burattin
+ */
 public interface Response {
 
 }
diff --git a/src/main/java/beamline/models/responses/package-info.java b/src/main/java/beamline/models/responses/package-info.java
new file mode 100644
index 0000000..a313399
--- /dev/null
+++ b/src/main/java/beamline/models/responses/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * This package contains all classes of the framework necessary to handle the
+ * responses of mining algorithms.
+ */
+package beamline.models.responses;
\ No newline at end of file
diff --git a/src/main/java/beamline/sources/CSVLogSource.java b/src/main/java/beamline/sources/CSVLogSource.java
index f528653..67ef94b 100644
--- a/src/main/java/beamline/sources/CSVLogSource.java
+++ b/src/main/java/beamline/sources/CSVLogSource.java
@@ -20,6 +20,12 @@ import io.reactivex.rxjava3.core.Observable;
 import io.reactivex.rxjava3.core.ObservableEmitter;
 import io.reactivex.rxjava3.core.ObservableOnSubscribe;
 
+/**
+ * This implementation of a {@link XesSource} produces events according to the
+ * events contained in a CSV file. This source produces a cold observable.
+ * 
+ * @author Andrea Burattin
+ */
 public class CSVLogSource implements XesSource {
 
 	private static XFactory xesFactory = new XFactoryNaiveImpl();
@@ -29,6 +35,26 @@ public class CSVLogSource implements XesSource {
 	private int activityNameColumn;
 	private CSVParser parser;
 	
+	/**
+	 * Constructs the source by providing a CSV parser.
+	 * 
+	 * <p>
+	 * A parser can be produced, for example with the following code:
+	 * <pre>
+	 * CSVParser parser = new CSVParserBuilder()
+	 *     .withSeparator(',')
+	 *     .withIgnoreQuotations(true)
+	 *     .build();
+	 * </pre>
+	 * 
+	 * @param filename the absolute path of the CSV file
+	 * @param caseIdColumn the id of the column containing the case id (counting
+	 * starts from 0)
+	 * @param activityNameColumn the id of the column containing the activity
+	 * name (counting starts from 0)
+	 * @param parser the parser to be used for parsing the CSV file
+	 * @throws IOException
+	 */
 	public CSVLogSource(String filename, int caseIdColumn, int activityNameColumn, CSVParser parser) throws IOException {
 		this.filename = filename;
 		this.caseIdColumn = caseIdColumn;
@@ -36,6 +62,16 @@ public class CSVLogSource implements XesSource {
 		this.parser = parser;
 	}
 	
+	/**
+	 * Constructs the source
+	 * 
+	 * @param filename the absolute path of the CSV file
+	 * @param caseIdColumn the id of the column containing the case id (counting
+	 * starts from 0)
+	 * @param activityNameColumn the id of the column containing the activity
+	 * name (counting starts from 0)
+	 * @throws IOException
+	 */
 	public CSVLogSource(String filename, int caseIdColumn, int activityNameColumn) throws IOException {
 		this(filename, caseIdColumn, activityNameColumn, null);
 	}
diff --git a/src/main/java/beamline/sources/MQTTXesSource.java b/src/main/java/beamline/sources/MQTTXesSource.java
index 26a0272..dccd90f 100644
--- a/src/main/java/beamline/sources/MQTTXesSource.java
+++ b/src/main/java/beamline/sources/MQTTXesSource.java
@@ -19,6 +19,20 @@ import org.eclipse.paho.client.mqttv3.MqttMessage;
 import io.reactivex.rxjava3.core.Observable;
 import io.reactivex.rxjava3.subjects.PublishSubject;
 
+/**
+ * This implementation of a {@link XesSource} produces events as they are
+ * observed in an MQTT-XES broker. This source produces a hot observable.
+ * 
+ * <p>
+ * Example of usage:
+ * <pre>
+ * XesSource source = new MQTTXesSource("tcp://broker.hivemq.com:1883", "topicBase", "processName");
+ * source.prepare();
+ * </pre>
+ * 
+ * @see {@link http://www.beamline.cloud/mqtt-xes/}
+ * @author Andrea Burattin
+ */
 public class MQTTXesSource implements XesSource {
 
 	private static XFactory xesFactory = new XFactoryNaiveImpl();
@@ -27,6 +41,13 @@ public class MQTTXesSource implements XesSource {
 	private String topicBase;
 	private PublishSubject<XTrace> ps;
 	
+	/**
+	 * Constructs the source
+	 * 
+	 * @param brokerHost the URL of the broker host
+	 * @param topicBase the base of the topic for the
+	 * @param processName the name of the process
+	 */
 	public MQTTXesSource(String brokerHost, String topicBase, String processName) {
 		this.brokerHost = brokerHost;
 		this.topicBase = topicBase;
diff --git a/src/main/java/beamline/sources/Source.java b/src/main/java/beamline/sources/Source.java
index 9fb5584..6befd91 100644
--- a/src/main/java/beamline/sources/Source.java
+++ b/src/main/java/beamline/sources/Source.java
@@ -2,9 +2,32 @@ package beamline.sources;
 
 import io.reactivex.rxjava3.core.Observable;
 
+/**
+ * This interface is the base type that should be extended by all sources to be
+ * used in the framework. When using a source implementing this type, the method
+ * {@link #prepare()} should be called <strong>before</strong>
+ * {@link #getObservable()}.
+ * 
+ * @author Andrea Burattin
+ *
+ * @param <T> the type of observable objects this interface will produce.
+ */
 public interface Source<T> {
 
+	/**
+	 * This method returns the observable created by the source. Before calling
+	 * this method, it is important to prepare the source by calling the
+	 * {@link #prepare()} method.
+	 * 
+	 * @return
+	 */
 	public Observable<T> getObservable();
 	
+	/**
+	 * This method is supposed to be called before the {@link #getObservable()}
+	 * one: it is in charge of preparing the source to be processed.
+	 * 
+	 * @throws Exception 
+	 */
 	public void prepare() throws Exception;
 }
diff --git a/src/main/java/beamline/sources/XesLogSource.java b/src/main/java/beamline/sources/XesLogSource.java
index 3b0a32b..5cce709 100644
--- a/src/main/java/beamline/sources/XesLogSource.java
+++ b/src/main/java/beamline/sources/XesLogSource.java
@@ -23,6 +23,13 @@ import io.reactivex.rxjava3.core.Observable;
 import io.reactivex.rxjava3.core.ObservableEmitter;
 import io.reactivex.rxjava3.core.ObservableOnSubscribe;
 
+/**
+ * This implementation of a {@link XesSource} produces events according to the
+ * events contained in an {@link XLog}. The events are first sorted according to
+ * their timestamp and then sent. This source produces a cold observable.
+ * 
+ * @author Andrea Burattin
+ */
 public class XesLogSource implements XesSource {
 
 	private static XFactory xesFactory = new XFactoryNaiveImpl();
@@ -31,14 +38,28 @@ public class XesLogSource implements XesSource {
 	private XLog log;
 	private List<XTrace> events;
 	
+	/**
+	 * Constructs a source from the path of a log
+	 * 
+	 * @param fileName the file containing the log to use. The file can be
+	 * either a file parsed by {@link XesXmlGZIPParser} or {@link XesXmlParser}
+	 * (i.e., extensions <code>.xes.gz</code> or <code>.xes</code>). If the file
+	 * is none of these, then {@link #prepare()} will throw an exception.
+	 */
 	public XesLogSource(String fileName) {
 		this.fileName = fileName;
 	}
 	
+	/**
+	 * Constructs a source from the given log
+	 * 
+	 * @param log the log to use as source
+	 */
 	public XesLogSource(XLog log) {
 		this.log = log;
 	}
 	
+	@Override
 	public Observable<XTrace> getObservable() {
 		return Observable.create(new ObservableOnSubscribe<XTrace>() {
 			@Override
@@ -50,6 +71,7 @@ public class XesLogSource implements XesSource {
 		});
 	}
 	
+	@Override
 	public void prepare() throws Exception {
 		if (log == null) {
 			parseLog(fileName);
diff --git a/src/main/java/beamline/sources/XesSource.java b/src/main/java/beamline/sources/XesSource.java
index 3f73b09..6ba5c65 100644
--- a/src/main/java/beamline/sources/XesSource.java
+++ b/src/main/java/beamline/sources/XesSource.java
@@ -2,6 +2,12 @@ package beamline.sources;
 
 import org.deckfour.xes.model.XTrace;
 
+/**
+ * This interface is supposed just to bind the type of {@link Source} to
+ * {@link XTrace}.
+ * 
+ * @author Andrea Burattin
+ */
 public interface XesSource extends Source<XTrace> {
 
 }
\ No newline at end of file
diff --git a/src/main/java/beamline/sources/package-info.java b/src/main/java/beamline/sources/package-info.java
new file mode 100644
index 0000000..49528de
--- /dev/null
+++ b/src/main/java/beamline/sources/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * This package contains all classes necessary to construct
+ * {@link io.reactivex.rxjava3.core.Observable}s that can be used in the rest of
+ * the project.
+ */
+package beamline.sources;
\ No newline at end of file
-- 
GitLab