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/events/VSRegisteredEvents.java | 38 +++++++++++++++++++++++-----
 1 file changed, 31 insertions(+), 7 deletions(-)

(limited to 'src/main/java/events/VSRegisteredEvents.java')

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