Cleanup docs

README.md

@@ -79,6 +79,7 @@ app = Server(address="127.0.0.1", port=9999)  # or Server() for defaults
 
 @app.endpoint("sum", description="Add two numbers")
 async def sum_endpoint(a: int, b: int) -> int:
+    """Add two numbers."""
     return a + b
 
 
@@ -171,26 +172,37 @@ await client.call("_synapse.ping")
 Returns published RPC methods:
 
 ```python
-await client.call("_synapse.methods")
+methods = await client.call("_synapse.methods")
+print(methods)
 ```
 
-Example response:
+For this endpoint:
+
+```python
+@app.endpoint("sum")
+async def sum_endpoint(a: int, b: int) -> int:
+    """Add two numbers."""
+    return a + b
+```
+
+The result is:
 
 ```python
 [
     {
         "name": "sum",
         "publish": True,
-        "description": "Add two numbers",
+        "description": "Add two numbers.",
     }
 ]
 ```
 
-Endpoints are published by default:
+Endpoints are published by default. Add a docstring to make them more useful to humans and agents inspecting `_synapse.methods`:
 
 ```python
-@app.endpoint("image.resize", description="Resize an image")
+@app.endpoint("image.resize")
 async def resize_image(...):
+    """Resize an image."""
     ...
 ```
 
@@ -292,8 +304,9 @@ if "code-review" in info["capabilities"]:
 ### 3. Publish tools as RPC methods
 
 ```python
-@app.endpoint("filesystem.search", description="Search files by regex")
+@app.endpoint("filesystem.search")
 async def search_files(pattern: str) -> list[str]:
+    """Search files by regex."""
     ...
 ```
 
@@ -324,9 +337,30 @@ finally:
 Synapse can run recurring async background jobs alongside your RPC server:
 
 ```python
+from synapse_p2p import Server
+
+app = Server()
+
+
 @app.background(5)
 async def heartbeat():
-    print("still alive")
+    print("heartbeat: server is still alive")
+
+
+@app.endpoint("sum")
+async def sum_endpoint(a: int, b: int) -> int:
+    return a + b
+
+
+if __name__ == "__main__":
+    app.run()
+```
+
+Startup output will include the task:
+
+```text
+Background Tasks:
+- heartbeat (5s)
 ```
 
 The task above runs roughly every five seconds. Exceptions are logged and do not stop future runs.

synapse_p2p/server.py

@@ -101,9 +101,10 @@ def _print_startup(self) -> None:
         for endpoint in self.endpoint_directory:
             print(f"- {endpoint}")
 
-        print("\nBackground Tasks:")
-        for task in self.background_executor.tasks:
-            print(f"- {task.name} ({task.period}s)")
+        if self.background_executor.tasks:
+            print("\nBackground Tasks:")
+            for task in self.background_executor.tasks:
+                print(f"- {task.name} ({task.period}s)")
         print()
 
     async def start(self) -> asyncio.Server: