From 7ee77637273e2e913cf19f078e9143ae6977f44f Mon Sep 17 00:00:00 2001
From: Paul Buetow <paul@buetow.org>
Date: Fri, 20 Jun 2025 19:25:10 +0300
Subject: Add comprehensive Javadoc documentation for public APIs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 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>
---
 src/main/java/core/VSMessage.java | 50 +++++++++++++++++++++++----------------
 1 file changed, 29 insertions(+), 21 deletions(-)

(limited to 'src/main/java/core/VSMessage.java')

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();
-- 
cgit v1.2.3