Add comments and docstrings to example plugin code

Explain what each section does and why, so new developers can
learn Endstone patterns by reading the template.

Author: wu-vincent

src/endstone_example/listener.py

@@ -1,18 +1,33 @@
+"""Event listener demonstrating how to respond to player events.
+
+Listeners are separate classes (not the Plugin itself) that hold @event_handler
+methods. Register them in on_enable with self.register_events(). This keeps
+event handling logic organized and out of the main plugin class.
+"""
+
 from endstone import ColorFormat
 from endstone.event import PlayerJoinEvent, PlayerQuitEvent, event_handler
 from endstone.plugin import Plugin
 
 
 class ExampleListener:
     def __init__(self, plugin: Plugin) -> None:
+        # Keep a reference to the plugin so we can use its logger and config.
         self._plugin = plugin
 
     @event_handler
     def on_player_join(self, event: PlayerJoinEvent) -> None:
+        """Called when a player joins the server."""
         player = event.player
+
+        # Modify the join message broadcast to all players.
+        # ColorFormat constants add Minecraft formatting codes.
         event.join_message = f"{ColorFormat.YELLOW}{player.name} joined the game"
+
+        # Log the player's network address (useful for debugging, not shown to players)
         self._plugin.logger.info(f"{player.name} joined from {player.address}")
 
     @event_handler
     def on_player_quit(self, event: PlayerQuitEvent) -> None:
+        """Called when a player leaves the server."""
         event.quit_message = f"{ColorFormat.YELLOW}{event.player.name} left the game"

src/endstone_example/plugin.py

@@ -1,3 +1,5 @@
+"""Example plugin demonstrating commands, configuration, and lifecycle methods."""
+
 from endstone import Player
 from endstone.command import Command, CommandSender, ConsoleCommandSender
 from endstone.plugin import Plugin
@@ -6,9 +8,14 @@
 
 
 class ExamplePlugin(Plugin):
+    # The prefix shown in log messages, e.g. [ExamplePlugin] Hello!
     prefix = "ExamplePlugin"
+
+    # Must match the major.minor version of the Endstone API you are targeting.
     api_version = "0.11"
 
+    # Commands are declared as a dict. Each key is the command name, and the value
+    # configures how it appears in-game. The "permissions" list controls who can use it.
     commands = {
         "hello": {
             "description": "Send a greeting",
@@ -17,6 +24,9 @@ class ExamplePlugin(Plugin):
         },
     }
 
+    # Permissions are declared separately from commands. The "default" field controls
+    # who gets the permission automatically: True = everyone, "op" = operators only,
+    # False = no one (must be explicitly granted).
     permissions = {
         "example.command.hello": {
             "description": "Allow users to use the /hello command.",
@@ -25,19 +35,42 @@ class ExamplePlugin(Plugin):
     }
 
     def on_enable(self) -> None:
+        """Called when the plugin is enabled. Use this for setup."""
+
+        # Copies config.toml to the plugin's data folder on first run.
+        # On subsequent runs it does nothing, preserving the user's edits.
         self.save_default_config()
+
+        # Register event listeners. Endstone scans the object for @event_handler
+        # methods and hooks them into the event system.
         self.register_events(ExampleListener(self))
+
         self.logger.info("ExamplePlugin enabled!")
 
     def on_disable(self) -> None:
+        """Called when the plugin is disabled. Use this for cleanup."""
         self.logger.info("ExamplePlugin disabled!")
 
     def on_command(self, sender: CommandSender, command: Command, args: list[str]) -> bool:
+        """Called when a player or the console runs one of this plugin's commands.
+
+        Args:
+            sender: Who ran the command (Player, ConsoleCommandSender, etc.).
+            command: The command that was executed.
+            args: The arguments passed after the command name.
+
+        Returns:
+            True if the command was handled successfully.
+        """
         match command.name:
             case "hello":
-                greeting = self.config["greeting"]  # from config.toml
+                # Read the greeting from config.toml (editable by server admins)
+                greeting = self.config["greeting"]
 
-                # Use isinstance to check the sender type
+                # Use isinstance to tailor behavior to the sender type.
+                # This is a common pattern since players and the console have
+                # different capabilities (e.g. players can receive chat messages,
+                # but the console can only write to the log).
                 if isinstance(sender, Player):
                     sender.send_message(f"{greeting}, {sender.name}!")
                 elif isinstance(sender, ConsoleCommandSender):