docs(examples): add comprehensive comments to explain each example's purpose and functionality

Author: observerw

examples/protocol.py

@@ -1,3 +1,9 @@
+# Example: Protocol-based capability checking for LSP clients
+#
+# This example demonstrates how to use Python's Protocol to define expected
+# capabilities for LSP clients and perform runtime checks to ensure clients
+# meet those requirements.
+
 from __future__ import annotations
 
 from typing import Protocol, runtime_checkable
@@ -17,14 +23,24 @@ class ExpectClientProtocol(
     WithRequestDefinition,
     Protocol,
 ):
-    """We expect the client to (at least) support 'references' and 'definition' requests."""
+    """Protocol defining minimum expected client capabilities.
+
+    This protocol specifies that any client implementing it must support
+    both 'references' and 'definition' LSP requests. Using @runtime_checkable
+    allows us to use isinstance() and issubclass() checks at runtime.
+    """
 
 
 class BadClient(
     LSPClient,
     WithRequestDocumentSymbol,
 ):
-    """The bad client does not meet our expectations."""
+    """Client that fails to meet protocol requirements.
+
+    This client only implements document symbol capability but lacks
+    the required references and definition capabilities, making it
+    incompatible with ExpectClientProtocol.
+    """
 
 
 class GoodClient(
@@ -33,8 +49,18 @@ class GoodClient(
     WithRequestDefinition,
     WithRequestCallHierarchy,
 ):
-    """The good client meets our expectations."""
+    """Client that satisfies protocol requirements.
+
+    This client implements both required capabilities (references and
+    definition) plus an additional capability (call hierarchy), making
+    it fully compatible with ExpectClientProtocol.
+    """
 
 
-assert not issubclass(BadClient, ExpectClientProtocol)
-assert issubclass(GoodClient, ExpectClientProtocol)
+# Runtime checks to verify protocol compliance
+assert not issubclass(
+    BadClient, ExpectClientProtocol
+)  # Should fail - missing required capabilities
+assert issubclass(
+    GoodClient, ExpectClientProtocol
+)  # Should pass - meets all requirements

examples/pyrefly.py

@@ -1,3 +1,9 @@
+# Example: Using Pyrefly LSP server for Python reference finding
+#
+# This example demonstrates how to use the Pyrefly language server
+# to find all references to a symbol in Python code. Pyrefly is a
+# Python language server that provides enhanced static analysis.
+
 from __future__ import annotations
 
 import anyio
@@ -10,20 +16,25 @@
 
 
 async def main():
+    # Initialize Pyrefly client with local server
     async with PyreflyClient(server=PyreflyLocalServer()) as client:
+        # Request references to PyreflyClient at line 21, column 19
         refs = await client.request_references(
             file_path="src/lsp_client/clients/pyrefly.py",
             position=Position(21, 19),
-            include_declaration=False,
+            include_declaration=False,  # Don't include the declaration itself
         )
 
         if not refs:
             print("No references found.")
             return
 
+        # Print all found references
         for ref in refs:
             print(f"Reference found at {ref.uri} - Range: {ref.range}")
 
+        # Verify that this example file contains a reference to PyreflyClient
+        # This demonstrates the reference finding functionality works correctly
         assert any(
             ref.uri.endswith(__file__)
             and ref.range
@@ -37,4 +48,4 @@ async def main():
 
 
 if __name__ == "__main__":
-    anyio.run(main)
+    anyio.run(main)  # Run the async example

examples/pyright_docker.py

@@ -1,3 +1,9 @@
+# Example: Using Pyright LSP server in Docker for Python definition lookup
+#
+# This example demonstrates how to use Pyright (Microsoft's Python language server)
+# running in a Docker container to find definition locations of Python symbols.
+# The Docker approach provides isolation and consistent environment setup.
+
 from __future__ import annotations
 
 from pathlib import Path
@@ -9,11 +15,15 @@
 
 
 async def main():
+    # Set up workspace directory and mount it in Docker
     workspace = Path.cwd()
     async with PyrightClient(
-        server=PyrightDockerServer(mounts=[workspace]),
+        server=PyrightDockerServer(
+            mounts=[workspace]
+        ),  # Mount workspace into container
         workspace=workspace,
     ) as client:
+        # Find definition of PyrightDockerServer at line 12, column 28
         refs = await client.request_definition_locations(
             file_path=__file__,
             position=Position(12, 28),
@@ -23,9 +33,10 @@ async def main():
             print("No definition locations found.")
             return
 
+        # Display all definition locations found
         for ref in refs:
             print(f"Definition location found at {ref.uri} - Range: {ref.range}")
 
 
 if __name__ == "__main__":
-    anyio.run(main)
+    anyio.run(main)  # Run the async example

examples/rust_analyzer.py

@@ -1,3 +1,9 @@
+# Example: Basic Rust Analyzer LSP client setup
+#
+# This example demonstrates how to initialize a Rust Analyzer client
+# and retrieve basic information about the language server configuration.
+# Rust Analyzer is the official language server for Rust programming language.
+
 from __future__ import annotations
 
 import anyio
@@ -9,9 +15,12 @@
 
 
 async def main():
+    # Initialize Rust Analyzer client with local server
     async with RustAnalyzerClient(server=RustAnalyzerLocalServer()) as client:
+        # Get and display the language ID for this client
+        # This should return "rust" for Rust Analyzer
         print(client.get_language_id())
 
 
 if __name__ == "__main__":
-    anyio.run(main)
+    anyio.run(main)  # Run the async example