Add comments to code blocks

README.md

@@ -51,7 +51,8 @@ The essential building blocks for building powerful P2P applications using Pear.
 
 | Name                                           | Description                                                                                                                       | Stability                                                        |
 |------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------|
-| [Hypercore](./building-blocks/hypercore.md)  | A distributed, secure append-only log for creating fast and scalable applications without a backend, as it is entirely P2P.         | <mark style="background-color:#80ff80;">**stable**</mark>        |
+| [Hypercore](./building-blocks/hypercore.md)  | A distributed, secure append-only log for creating fast and scalable applications without a backend, as it is entirely P2P.         | <mark style="background-color:#80ff80;">**stable**</mark>   |    
+| [Hyperbee](./building-blocks/hyperbee.md)| An append-only B-tree running on a Hypercore. Allows sorted iteration and more.| <mark style="background-color:#80ff80;">**stable**</mark>    |
 | [Hyperdrive](./building-blocks/hyperdrive.md)| A secure, real-time distributed file system that simplifies P2P file sharing and provides an efficient way to store and access data.| <mark style="background-color:#80ff80;">**stable**</mark>        |
 | [Autobase](./building-blocks/autobase.md)    | A "virtual Hypercore" layer over many Hypercores owned by many different peers.                                                     | <mark style="background-color: #8484ff;">**experimental**</mark> |
 | [Hyperdht](./building-blocks/hyperdht.md)    | The Distributed Hash Table (DHT) powering Hyperswarm.                                                                               | <mark style="background-color:#80ff80;">**stable**</mark>        |

guide/making-a-pear-desktop-app.md

@@ -187,14 +187,14 @@ Replace `app.js` with
 
 ``` js
 /* global Pear */
-import Hyperswarm from 'hyperswarm'
-import crypto from 'hypercore-crypto'
-import b4a from 'b4a'
-const { teardown } = Pear
+import Hyperswarm from 'hyperswarm'   // Module for P2P networking and connecting peers
+import crypto from 'hypercore-crypto' // Cryptographic functions for generating the key in app
+import b4a from 'b4a'                 // Module for buffer-to-string and vice-versa conversions 
+const { teardown } = Pear             // Cleanup function
 
 const swarm = new Hyperswarm()
 
-// Unnannounce the public key before exiting the process
+// Unannounce the public key before exiting the process
 // (This is not a requirement, but it helps avoid DHT pollution)
 teardown(() => swarm.destroy())
 

guide/making-a-pear-terminal-app.md

@@ -22,27 +22,37 @@ npm i bare-readline bare-tty hyperswarm b4a hypercore-crypto
 Replace `index.js` with
 
 ``` js
-import Hyperswarm from 'hyperswarm'
-import b4a from 'b4a'
-import crypto from 'hypercore-crypto'
-import readline from 'bare-readline'
-import tty from 'bare-tty'
-
-const { teardown, config } = Pear
-const key = config.args.pop()
-const shouldCreateSwarm = !key
+/* global Pear */
+import Hyperswarm from 'hyperswarm'   // Module for P2P networking and connecting peers
+import b4a from 'b4a'                 // Module for buffer-to-string and vice-versa conversions 
+import crypto from 'hypercore-crypto' // Cryptographic functions for generating the key in app
+import readline from 'bare-readline'  // Module for reading user input in terminal
+import tty from 'bare-tty'            // Module to control terminal behavior
+
+
+const { teardown, config } = Pear    // Import configuration options and cleanup functions from Pear
+const key = config.args.pop()       // Retrieve a potential chat room key from command-line arguments
+const shouldCreateSwarm = !key      // Flag to determine if a new chat room should be created
 const swarm = new Hyperswarm()
+
+// Unannounce the public key before exiting the process
+// (This is not a requirement, but it helps avoid DHT pollution)
+teardown(() => swarm.destroy())
+
 const rl = readline.createInterface({
   input: new tty.ReadStream(0),
   output: new tty.WriteStream(1)
 })
 
+// When there's a new connection, listen for new messages, and output them to the terminal
 swarm.on('connection', peer => {
   const name = b4a.toString(peer.remotePublicKey, 'hex').substr(0, 6)
   console.log(`[info] New peer joined, ${name}`)
   peer.on('data', message => appendMessage({ name, message }))
   peer.on('error', e => console.log(`Connection error: ${e}`))
 })
+
+// When there's updates to the swarm, update the peers count
 swarm.on('update', () => {
   console.log(`[info] Number of connections is now ${swarm.connections.size}`)
 })
@@ -53,15 +63,17 @@ if (shouldCreateSwarm) {
   await joinChatRoom(key)
 }
 
-rl.input.setMode(tty.constants.MODE_RAW)
+rl.input.setMode(tty.constants.MODE_RAW) // Enable raw input mode for efficient key reading
 rl.on('data', line => {
   sendMessage(line)
   rl.prompt()
 })
 rl.prompt()
 
 async function createChatRoom () {
+  // Generate a new random topic (32 byte string)
   const topicBuffer = crypto.randomBytes(32)
+  // Create a new chat room for the topic
   await joinSwarm(topicBuffer)
   const topic = b4a.toString(topicBuffer, 'hex')
   console.log(`[info] Created new chat room: ${topic}`)
@@ -74,16 +86,19 @@ async function joinChatRoom (topicStr) {
 }
 
 async function joinSwarm (topicBuffer) {
+    // Join the swarm with the topic. Setting both client/server to true means that this app can act as both.
   const discovery = swarm.join(topicBuffer, { client: true, server: true })
   await discovery.flushed()
 }
 
 function sendMessage (message) {
+  // Send the message to all peers (that you are connected to)
   const peers = [...swarm.connections]
   for (const peer of peers) peer.write(message)
 }
 
 function appendMessage ({ name, message }) {
+  // Output chat msgs to terminal
   console.log(`[${name}] ${message}`)
 }
 ```