diff --git a/lib/examples/demo.ts b/lib/examples/demo.ts
index 6239736..ba56058 100755
--- a/lib/examples/demo.ts
+++ b/lib/examples/demo.ts
@@ -6,14 +6,22 @@ import { CoreV1Api } from "../builtin/core@v1/mod.ts";
 
 const restClient = await autoDetectClient();
 
+
+// Set up a client for the apps/v1 API
 const appsApi = new AppsV1Api(restClient);
+
+// Iterate thru all deployments with pagination (to handle large lists effectively)
 for await (const deploy of readAllItems(t => appsApi.getDeploymentListForAllNamespaces({
-  limit: 5,
+  limit: 5, // note: tiny page size for demonstration purposes, 100-500 is common in practice
   continue: t,
 }))) {
   console.log(deploy.metadata?.namespace, deploy.metadata?.name);
 }
 
+
+// Set up a client for the core v1 API
 const coreApi = new CoreV1Api(restClient);
+
+// Get the first node from the cluster node list
 const {items: [node]} = await coreApi.getNodeList({limit: 1});
 console.log(node.status);
diff --git a/lib/examples/follow-logs.ts b/lib/examples/follow-logs.ts
index b250c6c..5861ada 100755
--- a/lib/examples/follow-logs.ts
+++ b/lib/examples/follow-logs.ts
@@ -28,4 +28,4 @@ for await (const line of logStream.pipeThrough(new TextLineStream())) {
   const date = new Date(line.slice(0, firstSpace));
   const logLine = line.slice(firstSpace+1);
   console.log(date, logLine);
-}
\ No newline at end of file
+}