Add comprehensive Javadoc documentation for public APIs

- Document core classes: VSTask, VSMessage, VSInternalProcess
- Document event interfaces: VSAbstractEvent, VSCopyableEvent, VSTime
- Document timestamp events: VSTimestampTriggeredEvent, VSLamportTimestampEvent
- Document protocol framework: VSAbstractProtocol methods
- Document VSSimulator and VSRegisteredEvents
- Add detailed method descriptions with parameter and return value docs
- Include usage examples and cross-references between related classes

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

11 files changed, 396 insertions, 115 deletions

diff --git a/src/main/java/core/VSInternalProcess.java b/src/main/java/core/VSInternalProcess.java
index 5442cd1..ddf378e 100644
--- a/src/main/java/core/VSInternalProcess.java
+++ b/src/main/java/core/VSInternalProcess.java
@@ -14,9 +14,24 @@ import simulator.VSSimulatorVisualization;
 import utils.VSPriorityQueue;
 
 /**
- * The class VSInternalProcess, an object of this class represents a process
- * of a simulator.
+ * Internal process implementation for the distributed systems simulator.
+ * This class extends {@link VSAbstractProcess} with simulation-specific features
+ * including:
+ * <ul>
+ *   <li>Time synchronization with global simulation clock</li>
+ *   <li>Clock variance simulation for realistic distributed behavior</li>
+ *   <li>Visual highlighting and color management</li>
+ *   <li>Vector clock monitoring for timestamp-triggered events</li>
+ *   <li>Process crash simulation</li>
+ *   <li>Protocol and event management</li>
+ * </ul>
+ * 
+ * <p>Each process maintains its own local time that drifts from global time
+ * based on configured clock variance, simulating realistic clock skew in
+ * distributed systems.</p>
  *
+ * @see VSAbstractProcess
+ * @see VSSimulatorVisualization
  * @author Paul C. Buetow
  */
 public class VSInternalProcess extends VSAbstractProcess {
@@ -39,8 +54,17 @@ public class VSInternalProcess extends VSAbstractProcess {
     }
 
     /**
-     * Called from the VSProcessEditor, after finishing editing! This makes
-     * sure that the VSInternalProcess object is using the up to date prefs!
+     * Updates this process's configuration from its preference settings.
+     * Called by {@link simulator.VSProcessEditor} after editing is complete
+     * to apply any configuration changes.
+     * 
+     * <p>This method updates:</p>
+     * <ul>
+     *   <li>Clock variance for time drift simulation</li>
+     *   <li>Local time value</li>
+     *   <li>Process colors</li>
+     *   <li>Random crash parameters</li>
+     * </ul>
      */
     public synchronized void updateFromPrefs() {
         setClockVariance(getFloat("process.clock.variance"));
@@ -50,8 +74,15 @@ public class VSInternalProcess extends VSAbstractProcess {
     }
 
     /**
-     * Called from the VSProcessEditor, before starting editing! This makes
-     * sure that the editor edits the up to date prefs of the process!
+     * Saves this process's current state to its preference settings.
+     * Called by {@link simulator.VSProcessEditor} before editing begins
+     * to ensure the editor shows current values.
+     * 
+     * <p>This method saves:</p>
+     * <ul>
+     *   <li>Current clock variance</li>
+     *   <li>Current local time</li>
+     * </ul>
      */
     public synchronized void updatePrefs() {
         setFloat("process.clock.variance", getClockVariance());
@@ -59,12 +90,22 @@ public class VSInternalProcess extends VSAbstractProcess {
     }
 
     /**
-     * Syncs the process' time. This method is using the clockOffset and
-     * clockVariance variables. This method is called repeatedly from the
-     * VSSimulatorVisualization in order to update the process' local and global
-     * time values.
+     * Synchronizes this process's time with the global simulation time.
+     * This method simulates realistic clock drift using the configured
+     * clock variance.
+     * 
+     * <p>The synchronization algorithm:</p>
+     * <ol>
+     *   <li>Calculates time elapsed since last sync</li>
+     *   <li>Advances local time by elapsed time</li>
+     *   <li>Applies clock drift based on variance</li>
+     *   <li>Accumulates fractional time in clockOffset</li>
+     *   <li>Ensures time never goes negative</li>
+     * </ol>
+     * 
+     * <p>Called repeatedly by {@link VSSimulatorVisualization} during simulation.</p>
      *
-     * @param globalTime the global time.
+     * @param globalTime the current global simulation time
      */
     public synchronized void syncTime(final long globalTime) {
         final long currentGlobalTimestep = globalTime - this.globalTime;
@@ -89,7 +130,11 @@ public class VSInternalProcess extends VSAbstractProcess {
     }
 
     /**
-     * Highlights the process.
+     * Activates visual highlighting for this process.
+     * The process's current color is saved and replaced with the highlight color.
+     * Use {@link #highlightOff()} to restore the original color.
+     * 
+     * @see #highlightOff()
      */
     public synchronized void highlightOn() {
         tmpColor = currentColor;
@@ -159,28 +204,47 @@ public class VSInternalProcess extends VSAbstractProcess {
     }
 
     /**
-     * Creates a random percentage 0..100 using the process' own pseudo
-     * random number generator object of the VSRandom class.
+     * Generates a random percentage value between 0 and 100 (inclusive).
+     * Uses this process's dedicated random number generator to ensure
+     * reproducible results for a given random seed.
+     * 
+     * <p>This method is commonly used for:</p>
+     * <ul>
+     *   <li>Probabilistic event triggering</li>
+     *   <li>Random crash simulation</li>
+     *   <li>Message loss simulation</li>
+     * </ul>
      *
-     * @return A random percentage 0..100.
+     * @return a random integer between 0 and 100 inclusive
+     * @see utils.VSRandom
      */
     public synchronized int getRandomPercentage() {
         return random.nextInt() % constants.VSConstants.PERCENTAGE_RANGE;
     }
 
     /**
-     * Adds the clock offset. This method is used by the task manager. The
-     * clock offset identifies if the local time of the process has changed and
-     * how much..
+     * Adds to this process's clock offset, adjusting its local time drift.
+     * Used by the task manager when tasks modify process time.
+     * 
+     * <p>The clock offset accumulates fractional time units that are
+     * converted to whole time units during {@link #syncTime(long)}.</p>
      *
-     * @param add the clock offset to add.
+     * @param add the amount to add to the clock offset (can be negative)
+     * @see VSTaskManager#runTasks(long)
      */
     public synchronized void addClockOffset(long add) {
         this.clockOffset += add;
     }
 
     /**
-     * The process' state is 'play'. Called by the simulator canvas.
+     * Transitions this process to the 'playing' state.
+     * The process resumes normal operation and its color changes
+     * to indicate running status.
+     * 
+     * <p>Called by the simulator when starting or resuming simulation.</p>
+     * 
+     * @see #pause()
+     * @see #finish()
      */
     public synchronized void play() {
         isPaused = false;
@@ -188,7 +252,14 @@ public class VSInternalProcess extends VSAbstractProcess {
     }
 
     /**
-     * The process' state is 'pause'. Called by the simulator canvas.
+     * Transitions this process to the 'paused' state.
+     * The process stops executing and its color changes
+     * to indicate stopped status.
+     * 
+     * <p>Called by the simulator when pausing simulation.</p>
+     * 
+     * @see #play()
+     * @see #finish()
      */
     public synchronized void pause() {
         isPaused = true;
@@ -196,7 +267,13 @@ public class VSInternalProcess extends VSAbstractProcess {
     }
 
     /**
-     * The process' state is 'Finish'. Called by the simulator canvas.
+     * Transitions this process to the 'finished' state.
+     * The process stops executing and returns to its default color.
+     * 
+     * <p>Called by the simulator when ending simulation.</p>
+     * 
+     * @see #play()
+     * @see #pause()
      */
     public synchronized void finish() {
         isPaused = true;
@@ -222,11 +299,15 @@ public class VSInternalProcess extends VSAbstractProcess {
     }
 
     /**
-     * Checks if the time has been modified. by a task.
-     * This mehod is needed by the task manager in order to add a clock offset
-     * to the process object.
+     * Checks if this process's time has been modified by a task.
+     * The task manager uses this flag to determine if clock offset
+     * adjustments are needed after task execution.
+     * 
+     * <p>This flag is set when tasks directly modify the process's
+     * local time, requiring synchronization adjustments.</p>
      *
-     * @return true, if yes
+     * @return true if the time has been modified since last check
+     * @see VSTaskManager#runTasks(long)
      */
     public synchronized boolean timeModified() {
         return timeModified;
diff --git a/src/main/java/core/VSMessage.java b/src/main/java/core/VSMessage.java
index a7b48e6..130bd53 100644
--- a/src/main/java/core/VSMessage.java
+++ b/src/main/java/core/VSMessage.java
@@ -79,64 +79,71 @@ public class VSMessage extends VSPrefs {
     }
 
     /**
-     * Gets the protocol name of the message.
+     * Gets the human-readable protocol name associated with this message.
+     * The name is retrieved from the registered events based on the protocol classname.
      *
-     * @return The protocol name of the message.
+     * @return the localized protocol name, or null if not found
      */
     public String getName() {
         return VSRegisteredEvents.getNameByClassname(getProtocolClassname());
     }
 
     /**
-     * Gets the protocol classname.
+     * Gets the fully qualified classname of the protocol that created this message.
+     * This is used to identify which protocol handler should process the message.
      *
-     * @return The protocol classname of the message.
+     * @return the protocol's full classname (e.g., "protocols.implementations.VSPingPongProtocol")
      */
     public String getProtocolClassname() {
         return protocolClassname;
     }
 
     /**
-     * Gets the message id.
+     * Gets the unique identifier for this message.
+     * Each message is assigned a sequential ID when created.
      *
-     * @return The id of the message.
+     * @return the unique message ID
      */
     public long getMessageID() {
         return messageID;
     }
 
     /**
-     * Gets a reference of the sending process.
+     * Gets the process that sent this message.
+     * This can be used to identify the sender and access sender information.
      *
-     * @return The process which sent this message.
+     * @return the process that created and sent this message
      */
     public VSAbstractProcess getSendingProcess() {
         return sendingProcess;
     }
 
     /**
-     * Gets the lamport time.
+     * Gets the Lamport timestamp of the sending process at the time this message was sent.
+     * This is used for logical ordering of events in the distributed system.
      *
-     * @return The lamport time of the sending process.
+     * @return the sender's Lamport time when the message was created
      */
     public long getLamportTime() {
         return lamportTime;
     }
 
     /**
-     * Gets the vector time.
+     * Gets the vector clock of the sending process at the time this message was sent.
+     * This is used for determining causality between events in the distributed system.
      *
-     * @return The vector time of the sending process.
+     * @return a copy of the sender's vector clock when the message was created
      */
     public VSVectorTime getVectorTime() {
         return vectorTime;
     }
 
     /**
-     * Checks if the message has been sent by a server or a client.
+     * Checks whether this message was sent by a server or client protocol instance.
+     * This distinction is important for protocols that have different behavior
+     * for server and client roles.
      *
-     * @return true, if the message has been sent by a server. false, if the
-     *	message has been sent by a client.
+     * @return true if sent by a server protocol instance, false if sent by a client
      */
     public boolean isServerMessage() {
         return isServerMessage;
@@ -160,20 +167,21 @@ public class VSMessage extends VSPrefs {
     }
 
     /**
-     * Extended string representation of the message object.
+     * Returns an extended string representation of this message.
+     * This includes the basic message information plus all stored preferences/data.
      *
-     * @return Extended string representation of the message object.
+     * @return detailed string representation including ID, protocol, and all message data
      */
     public String toStringFull() {
         return toString() + "; " + super.toString();
     }
 
     /**
-     * Compares two messages.
+     * Compares this message with another message for equality.
+     * Two messages are considered equal if they have the same message ID.
      *
-     * @param message The message to compare with.
-     *
-     * @return true, if the messages have the same id. Otherwise false.
+     * @param message the message to compare with this message
+     * @return true if both messages have the same ID, false otherwise
      */
     public boolean equals(VSMessage message) {
         return messageID == message.getMessageID();
diff --git a/src/main/java/core/VSTask.java b/src/main/java/core/VSTask.java
index cc43f1c..81b098e 100644
--- a/src/main/java/core/VSTask.java
+++ b/src/main/java/core/VSTask.java
@@ -257,7 +257,12 @@ public class VSTask implements Comparable<Object>, VSSerializable {
     }
 
     /**
-     * Runs the task.
+     * Executes this task by running its associated event.
+     * This method is called by the task manager when the task's scheduled time arrives.
+     * If the event requires it, this will also increase the process's timestamps.
+     * 
+     * @see VSAbstractEvent#onStart()
+     * @see VSAbstractEvent#shouldIncreaseTimestamps()
      */
     public void run() {
         if (event.getProcess() == null)
@@ -279,18 +284,22 @@ public class VSTask implements Comparable<Object>, VSSerializable {
     }
 
     /**
-     * Sets the task time.
+     * Sets the scheduled execution time for this task.
+     * For global-timed tasks, this is in global simulation time units.
+     * For local-timed tasks, this is in the process's local time units.
      *
-     * @param taskTime the task time
+     * @param taskTime the time when this task should execute
      */
     public void setTaskTime(long taskTime) {
         this.taskTime = taskTime;
     }
 
     /**
-     * Sets the process.
+     * Sets the process that owns this task.
+     * This method only updates the process if it differs from the current one.
+     * It also updates the event's process reference.
      *
-     * @param process the process
+     * @param process the process that will own and execute this task
      */
     public void setProcess(VSInternalProcess process) {
         /* Only do it if the process differs */
diff --git a/src/main/java/core/time/VSTime.java b/src/main/java/core/time/VSTime.java
index d46e0e4..20806d6 100644
--- a/src/main/java/core/time/VSTime.java
+++ b/src/main/java/core/time/VSTime.java
@@ -1,22 +1,31 @@
 package core.time;
 
 /**
- * This interface is a guidline for general time format classes.
+ * Interface for time representations in the distributed simulator.
+ * This interface provides a common contract for different time implementations
+ * including Lamport logical time and vector clocks.
+ * 
+ * <p>All time implementations must track the global simulation time
+ * and provide a string representation for display purposes.</p>
  *
+ * @see VSLamportTime
+ * @see VSVectorTime
  * @author Paul C. Buetow
  */
 public interface VSTime {
     /**
-     * Gets the global time.
+     * Gets the global simulation time when this time value was recorded.
+     * This allows correlation between logical time and simulation time.
      *
-     * @return The global time
+     * @return the global simulation time in milliseconds
      */
     public long getGlobalTime();
 
     /**
-     * Returns a string representation.
+     * Returns a string representation of this time value.
+     * The format depends on the specific time implementation.
      *
-     * @return The representation of the implementing object as a string
+     * @return string representation suitable for display or logging
      */
     public String toString();
 }
diff --git a/src/main/java/events/VSAbstractEvent.java b/src/main/java/events/VSAbstractEvent.java
index 37c3d59..1bbfc05 100644
--- a/src/main/java/events/VSAbstractEvent.java
+++ b/src/main/java/events/VSAbstractEvent.java
@@ -42,63 +42,71 @@ abstract public class VSAbstractEvent extends VSSerializablePrefs {
     private String eventClassname;
 
     /**
-     * Check if this event is an internal event.
+     * Checks if this event is an internal event.
+     * Internal events are system events that don't directly correspond to user actions.
      * 
-     * @return true if this is an internal event
+     * @return true if this is an internal event, false otherwise
      */
     public boolean isInternalEvent() {
         return false;
     }
     
     /**
-     * Check if this event is serializable.
+     * Checks if this event can be serialized for saving/loading simulations.
+     * Most events are serializable, but some runtime-only events may not be.
      * 
-     * @return true if this event is serializable
+     * @return true if this event can be serialized, false otherwise
      */
     public boolean isSerializable() {
         return true;
     }
     
     /**
-     * Check if this event is a message receive event.
+     * Checks if this event represents receiving a message.
+     * Message receive events are triggered when a process receives a message.
      * 
-     * @return true if this is a message receive event
+     * @return true if this is a message receive event, false otherwise
      */
     public boolean isMessageReceiveEvent() {
         return false;
     }
     
     /**
-     * Check if this event is a process recover event.
+     * Checks if this event represents a process recovery.
+     * Process recover events restore a crashed process to operational state.
      * 
-     * @return true if this is a process recover event
+     * @return true if this is a process recover event, false otherwise
      */
     public boolean isProcessRecoverEvent() {
         return false;
     }
     
     /**
-     * Check if this event is a process crash event.
+     * Checks if this event represents a process crash.
+     * Process crash events simulate process failures in the distributed system.
      * 
-     * @return true if this is a process crash event
+     * @return true if this is a process crash event, false otherwise
      */
     public boolean isProcessCrashEvent() {
         return false;
     }
     
     /**
-     * Check if this event is a protocol event.
+     * Checks if this event is a protocol-related event.
+     * Protocol events manage protocol activation/deactivation.
      * 
-     * @return true if this is a protocol event
+     * @return true if this is a protocol event, false otherwise
      */
     public boolean isProtocolEvent() {
         return false;
     }
     
     /**
-     * Check if this event should trigger timestamp increases when executed.
+     * Determines if executing this event should increase the process's timestamps.
+     * Most events increase timestamps, but some internal events may not.
+     * This affects both Lamport and vector clocks based on preferences.
      * 
-     * @return true if timestamps should be increased
+     * @return true if timestamps should be increased when this event executes
      */
     public boolean shouldIncreaseTimestamps() {
         return true;
diff --git a/src/main/java/events/VSCopyableEvent.java b/src/main/java/events/VSCopyableEvent.java
index 23125ce..0b93f9e 100644
--- a/src/main/java/events/VSCopyableEvent.java
+++ b/src/main/java/events/VSCopyableEvent.java
@@ -1,16 +1,31 @@
 package events;
 
 /**
- * The interface VSCopyableEvent, all events which implement this class
- * are copyable.
+ * Interface for events that support copying.
+ * Events that implement this interface can be duplicated, which is useful
+ * for creating multiple instances of the same event or for event scheduling.
+ * 
+ * <p>To make an event copyable:</p>
+ * <ol>
+ *   <li>Implement this interface</li>
+ *   <li>Override initCopy() to copy all event-specific state</li>
+ *   <li>The framework will handle creating the new instance</li>
+ * </ol>
+ * 
+ * <p>Events that don't implement this interface will throw
+ * {@link exceptions.VSEventNotCopyableException} when copy is attempted.</p>
  *
+ * @see VSAbstractEvent#getCopy()
+ * @see exceptions.VSEventNotCopyableException
  * @author Paul C. Buetow
  */
 public interface VSCopyableEvent {
     /**
-     * Fills a copy of this event with its values
+     * Initializes a copy of this event with all necessary state.
+     * This method should copy all event-specific fields to the provided copy.
+     * The copy will already be initialized with the same process and basic properties.
      *
-     * @param copy The copy
+     * @param copy the event instance to initialize with this event's state
      */
     public void initCopy(VSAbstractEvent copy);
 }
diff --git a/src/main/java/events/VSRegisteredEvents.java b/src/main/java/events/VSRegisteredEvents.java
index d2cc758..92deeb0 100644
--- a/src/main/java/events/VSRegisteredEvents.java
+++ b/src/main/java/events/VSRegisteredEvents.java
@@ -11,11 +11,23 @@ import prefs.VSPrefs;
 import utils.VSClassLoader;
 
 /**
- * The class VSRegisteredEvents. This class is responsible to manage all
- * events. It manages the event classnames, the event shortnames and the event
- * names. It also checks if a protocol (which is an event as well) has
- * variables which are editable through the GUI of the simulator.
- *
+ * Registry and manager for all available events and protocols in the simulator.
+ * This class provides a centralized location for:
+ * <ul>
+ *   <li>Registering event and protocol implementations</li>
+ *   <li>Mapping between class names, short names, and display names</li>
+ *   <li>Identifying which protocols have editable parameters</li>
+ *   <li>Managing client/server variable metadata for protocols</li>
+ * </ul>
+ * 
+ * <p>All events and protocols must be registered in {@link #init(VSPrefs)}
+ * to be available in the simulator. The registry uses reflection to discover
+ * protocol properties and determine which ones expose editable parameters.</p>
+ * 
+ * <p>This is a static utility class and cannot be instantiated.</p>
+ * 
+ * @see VSAbstractEvent
+ * @see protocols.VSAbstractProtocol
  * @author Paul C. Buetow
  */
 public final class VSRegisteredEvents {
@@ -52,9 +64,21 @@ public final class VSRegisteredEvents {
     private static VSPrefs prefs;
 
     /**
-     * Registers available events.
+     * Initializes the event registry with all available events and protocols.
+     * This method must be called before any events or protocols can be used.
+     * 
+     * <p>The initialization process:</p>
+     * <ol>
+     *   <li>Registers all built-in events (crashes, recoveries, timestamps)</li>
+     *   <li>Registers all protocol implementations</li>
+     *   <li>Uses reflection to discover editable protocol parameters</li>
+     *   <li>Builds metadata for protocol client/server variables</li>
+     * </ol>
+     * 
+     * <p>To add a new event or protocol, add a registerEvent() call here
+     * with the fully qualified class name.</p>
      *
-     * @param prefs_ the prefs_
+     * @param prefs_ the preferences object for the simulator
      */
     public static void init(VSPrefs prefs_) {
         prefs = prefs_;
diff --git a/src/main/java/events/implementations/VSLamportTimestampEvent.java b/src/main/java/events/implementations/VSLamportTimestampEvent.java
index 28da7dc..e82ea24 100644
--- a/src/main/java/events/implementations/VSLamportTimestampEvent.java
+++ b/src/main/java/events/implementations/VSLamportTimestampEvent.java
@@ -6,11 +6,28 @@ import core.VSInternalProcess;
  * Concrete implementation of a Lamport timestamp-triggered event.
  * This event fires when a specific Lamport timestamp condition is met.
  * 
- * Example usage:
- * - Fire when Lamport time equals 10
- * - Fire when Lamport time reaches 50 or greater
- * - Fire when Lamport time is less than 5
+ * <p>This class allows you to create events that trigger based on Lamport logical time.
+ * You can specify conditions such as:</p>
+ * <ul>
+ *   <li>Fire when Lamport time equals 10</li>
+ *   <li>Fire when Lamport time reaches 50 or greater</li>
+ *   <li>Fire when Lamport time is less than 5</li>
+ * </ul>
+ * 
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * // Create event that fires when Lamport time reaches 100
+ * VSLamportTimestampEvent event = new VSLamportTimestampEvent(
+ *     100, ComparisonOperator.GREATER_EQUAL, "Checkpoint reached");
+ * 
+ * // Add custom action
+ * event.setCustomAction(() -> {
+ *     System.out.println("Lamport time 100 reached!");
+ * });
+ * }</pre>
  *
+ * @see VSTimestampTriggeredEvent
+ * @see VSTimestampMonitorEvent
  * @author Paul C. Buetow
  */
 public class VSLamportTimestampEvent extends VSTimestampTriggeredEvent {
diff --git a/src/main/java/events/implementations/VSTimestampTriggeredEvent.java b/src/main/java/events/implementations/VSTimestampTriggeredEvent.java
index ef99104..c5e5386 100644
--- a/src/main/java/events/implementations/VSTimestampTriggeredEvent.java
+++ b/src/main/java/events/implementations/VSTimestampTriggeredEvent.java
@@ -14,7 +14,21 @@ import serialize.VSSerialize;
 /**
  * Abstract base class for timestamp-triggered events that fire when specific
  * Lamport or vector clock conditions are met.
- *
+ * 
+ * <p>This class provides the foundation for creating events that trigger based on
+ * timestamp conditions. Subclasses can define events that fire when:</p>
+ * <ul>
+ *   <li>Lamport time reaches a specific value</li>
+ *   <li>Vector clock matches certain conditions</li>
+ *   <li>Custom timestamp comparisons are satisfied</li>
+ * </ul>
+ * 
+ * <p>Events can use various comparison operators (equal, greater than, less than, etc.)
+ * and will only trigger once when their condition is first met.</p>
+ * 
+ * @see VSLamportTimestampEvent
+ * @see VSVectorTimestampEvent
+ * @see VSTimestampMonitorEvent
  * @author Paul C. Buetow
  */
 public abstract class VSTimestampTriggeredEvent extends VSAbstractEvent implements VSCopyableEvent {
diff --git a/src/main/java/protocols/VSAbstractProtocol.java b/src/main/java/protocols/VSAbstractProtocol.java
index d54eac2..505a6aa 100644
--- a/src/main/java/protocols/VSAbstractProtocol.java
+++ b/src/main/java/protocols/VSAbstractProtocol.java
@@ -27,6 +27,12 @@ abstract public class VSAbstractProtocol extends VSAbstractEvent {
     /** The protocol has an onClientStart method */
     protected static final boolean HAS_ON_CLIENT_START = false;
     
+    /**
+     * Protocols do not increase timestamps when executed.
+     * Only regular events and messages increase timestamps.
+     * 
+     * @return always false for protocol events
+     */
     @Override
     public boolean shouldIncreaseTimestamps() {
         return false;
@@ -67,9 +73,18 @@ abstract public class VSAbstractProtocol extends VSAbstractEvent {
     }
 
     /**
-     * Sends a message.
+     * Sends a message from this protocol to other processes.
+     * This method automatically:
+     * <ul>
+     *   <li>Increases the process's Lamport and vector timestamps</li>
+     *   <li>Wraps the message in a {@link VSMessageStub}</li>
+     *   <li>Marks the message as server or client based on current context</li>
+     *   <li>Delegates to the process for actual transmission</li>
+     * </ul>
      *
      * @param message the message to send
+     * @see VSMessageStub
+     * @see VSInternalProcess#sendMessage(VSMessage)
      */
     public void sendMessage(VSMessage message) {
         if (process == null)
@@ -161,9 +176,17 @@ abstract public class VSAbstractProtocol extends VSAbstractEvent {
     }
 
     /**
-     * On message recv.
+     * Handles incoming message reception for this protocol.
+     * This method:
+     * <ul>
+     *   <li>Filters out messages for other protocols</li>
+     *   <li>Ensures server/client initialization</li>
+     *   <li>Delegates to onServerRecv() or onClientRecv() based on context</li>
+     * </ul>
      *
-     * @param message the message
+     * @param message the received message
+     * @see #onServerRecv(VSMessage)
+     * @see #onClientRecv(VSMessage)
      */
     public final void onMessageRecvStart(VSMessage message) {
         if (isIncorrectProtocol(message))
@@ -185,14 +208,19 @@ abstract public class VSAbstractProtocol extends VSAbstractEvent {
     }
 
     /**
-     * Check's if its a relevant message.
+     * Checks if a message is relevant for this protocol instance.
+     * A message is relevant if:
+     * <ul>
+     *   <li>It belongs to this protocol (same class name)</li>
+     *   <li>It's a server message and this is a client</li>
+     *   <li>It's a client message and this is a server</li>
+     * </ul>
+     * 
+     * <p>This ensures proper client-server communication where:
+     * clients only receive server messages and servers only receive client messages.</p>
      *
      * @param message the message to check
-     *
-     * @return true, if it's a relevant meessage. false if the protocol
-     *	is wrong or if the server recv a server message/the client recv a
-     * 	client message. Clients should only recv server messages and servers
-     *	should only recv client messages.
+     * @return true if the message should be processed by this protocol instance
      */
     public final boolean isRelevantMessage(VSMessage message) {
         if (isIncorrectProtocol(message))
@@ -280,10 +308,17 @@ abstract public class VSAbstractProtocol extends VSAbstractEvent {
     }
 
     /**
-     * Reschedules the protocol for a new time and runs onClientSchedule or
-     *	onServerSchedule
+     * Schedules this protocol to execute at a specific local time.
+     * When the scheduled time arrives, either {@link #onServerSchedule()} or
+     * {@link #onClientSchedule()} will be called based on the current context.
+     * 
+     * <p>The schedule is tracked separately for server and client contexts,
+     * allowing independent scheduling for each role.</p>
      *
-     * @param time The process' local time to run the schedule at.
+     * @param time the process's local time when the schedule should execute
+     * @see #onServerSchedule()
+     * @see #onClientSchedule()
+     * @see VSProtocolScheduleEvent
      */
     public final void scheduleAt(long time) {
         VSInternalProcess internalProcess = (VSInternalProcess) process;
@@ -320,56 +355,104 @@ abstract public class VSAbstractProtocol extends VSAbstractEvent {
     }
 
     /**
-     * On client init.
+     * Called once when the protocol's client functionality is first initialized.
+     * Subclasses should implement this to set up client-specific state,
+     * initialize data structures, and prepare for client operations.
+     * 
+     * <p>This method is called before the first {@link #onClientStart()}
+     * or {@link #onClientRecv(VSMessage)} invocation.</p>
      */
     abstract public void onClientInit();
 
     /**
-     * On client start.
+     * Called when the client protocol should begin its main operation.
+     * Only used if the protocol was created with {@code hasOnServerStart = false}.
+     * 
+     * <p>Default implementation does nothing. Override this method to implement
+     * client-initiated protocol behavior.</p>
      */
     public void onClientStart() { };
 
     /**
-     * On client reset.
+     * Called when the protocol's client state should be reset.
+     * Subclasses should implement this to clear client-specific state
+     * and prepare for potential re-initialization.
+     * 
+     * <p>All client schedules are automatically cleared before this method is called.</p>
      */
     abstract public void onClientReset();
 
     /**
-     * On client schedule.
+     * Called when a scheduled client event occurs.
+     * Subclasses should implement this to handle periodic client operations
+     * or delayed client actions.
+     * 
+     * <p>To schedule this method, use {@link #scheduleAt(long)} while in client context.</p>
+     * 
+     * @see #scheduleAt(long)
      */
     abstract public void onClientSchedule();
 
     /**
-     * On client recv.
+     * Called when the client receives a message from a server.
+     * Subclasses should implement this to handle incoming server messages
+     * and update client state accordingly.
+     * 
+     * <p>The message is guaranteed to be a server message for this protocol.</p>
      *
-     * @param message the message
+     * @param message the server message received
+     * @see #sendMessage(VSMessage)
      */
     abstract public void onClientRecv(VSMessage message);
 
     /**
-     * On server init.
+     * Called once when the protocol's server functionality is first initialized.
+     * Subclasses should implement this to set up server-specific state,
+     * initialize data structures, and prepare for server operations.
+     * 
+     * <p>This method is called before the first {@link #onServerStart()}
+     * or {@link #onServerRecv(VSMessage)} invocation.</p>
      */
     abstract public void onServerInit();
 
     /**
-     * On server start.
+     * Called when the server protocol should begin its main operation.
+     * Only used if the protocol was created with {@code hasOnServerStart = true}.
+     * 
+     * <p>Default implementation does nothing. Override this method to implement
+     * server-initiated protocol behavior.</p>
      */
     public void onServerStart() { };
 
     /**
-     * On server reset.
+     * Called when the protocol's server state should be reset.
+     * Subclasses should implement this to clear server-specific state
+     * and prepare for potential re-initialization.
+     * 
+     * <p>All server schedules are automatically cleared before this method is called.</p>
      */
     abstract public void onServerReset();
 
     /**
-     * On server recv.
+     * Called when the server receives a message from a client.
+     * Subclasses should implement this to handle incoming client messages
+     * and update server state accordingly.
+     * 
+     * <p>The message is guaranteed to be a client message for this protocol.</p>
      *
-     * @param message the message
+     * @param message the client message received
+     * @see #sendMessage(VSMessage)
      */
     abstract public void onServerRecv(VSMessage message);
 
     /**
-     * On server schedule.
+     * Called when a scheduled server event occurs.
+     * Subclasses should implement this to handle periodic server operations
+     * or delayed server actions.
+     * 
+     * <p>To schedule this method, use {@link #scheduleAt(long)} while in server context.</p>
+     * 
+     * @see #scheduleAt(long)
      */
     abstract public void onServerSchedule();
 
diff --git a/src/main/java/simulator/VSSimulator.java b/src/main/java/simulator/VSSimulator.java
index 4515357..c6bdfad 100644
--- a/src/main/java/simulator/VSSimulator.java
+++ b/src/main/java/simulator/VSSimulator.java
@@ -55,10 +55,23 @@ import serialize.VSSerializable;
 import serialize.VSSerialize;
 
 /**
- * The class VSSimulator, an object of this class represents a whole simulator.
- * It may be, that several parallel simulators exist. They are independent
- * fron each other.
- *
+ * Main simulator control panel and coordinator for the distributed systems simulator.
+ * This class manages the simulation UI and coordinates between various components:
+ * <ul>
+ *   <li>Process management and visualization</li>
+ *   <li>Task scheduling and execution</li>
+ *   <li>Event and protocol management</li>
+ *   <li>Logging and filtering</li>
+ *   <li>Simulation control (play, pause, reset)</li>
+ * </ul>
+ * 
+ * <p>The simulator provides both a graphical interface for controlling the
+ * simulation and programmatic access to simulation state. Multiple independent
+ * simulators can exist in parallel without interfering with each other.</p>
+ * 
+ * @see VSSimulatorVisualization
+ * @see VSTaskManager
+ * @see VSInternalProcess
  * @author Paul C. Buetow
  */
 public class VSSimulator extends JPanel implements VSSerializable {