PCX review. Adding glossary term for "event context", definition TBC.

Author: Oxyjun

src/content/docs/durable-objects/api/state.mdx

@@ -5,7 +5,7 @@ sidebar:
   order: 4
 ---
 
-import { Tabs, TabItem } from "~/components";
+import { Tabs, TabItem, GlossaryTooltip } from "~/components";
 
 ## Description
 
@@ -53,7 +53,7 @@ export class MyDurableObject extends DurableObject {
 
 ### `waitUntil`
 
-`waitUntil` waits until the promise which is passed as a parameter resolves and can extends an event context up to 30 seconds after the last client disconnects.
+`waitUntil` waits until the promise which is passed as a parameter resolves and can extends an <GlossaryTooltip term= "event context">event context</GlossaryTooltip> up to 30 seconds after the last client disconnects.
 
 :::note[`waitUntil` is not necessary]
 
@@ -71,13 +71,13 @@ The event context for a Durable Objects extends at least 60 seconds after the la
 
 ### `blockConcurrencyWhile`
 
-`blockConcurrencyWhile` executes an async callback while blocking any other events from being delivered to the Durable Object instance until the callback completes. This method guarantees ordering and prevents concurrent requests. All events that were not explicitly initiated as part of the callback itself will be blocked. Once the callback completes, All other events will be delivered.
+`blockConcurrencyWhile` executes an async callback while blocking any other events from being delivered to the Durable Object instance until the callback completes. This method guarantees ordering and prevents concurrent requests. All events that were not explicitly initiated as part of the callback itself will be blocked. Once the callback completes, all other events will be delivered.
 
-`blockConcurrencyWhile` is commonly used within the constructor of the Durable Object class to enforce that initialization must occur before any requests are delivered. Another use case is executing `async` operations based on the current state of the Durable Object instance and using `blockConcurrencyWhile` to prevent that state from changing while yeilding the event loop.
+`blockConcurrencyWhile` is commonly used within the constructor of the Durable Object class to enforce initialization to occur before any requests are delivered. Another use case is executing `async` operations based on the current state of the Durable Object instance and using `blockConcurrencyWhile` to prevent that state from changing while yielding the event loop.
 
 If the callback throws an exception, the object will be terminated and reset. This ensures that the object cannot be left stuck in an uninitialized state if something fails unexpectedly. To avoid this behavior, enclose the body of your callback in a `try...catch` block to ensure it cannot throw an exception.
 
-To help mitigate deadlocks there is a 30s timeout applied when executing the callback. If this timeout is exceeded the Durable Object instance will be reset. It is best practice to have the callback do as little work as possible to improve overall request throughput to the Durable Object instance.
+To help mitigate deadlocks there is a 30 second timeout applied when executing the callback. If this timeout is exceeded, the Durable Object instance will be reset. It is best practice to have the callback do as little work as possible to improve overall request throughput to the Durable Object instance.
 
 ```js
 // Durable Object
@@ -131,7 +131,7 @@ The WebSocket Hibernation API permits a maximum of 32,768 WebSocket connections
 
 :::note[`waitUntil` is not necessary]
 
-Disconnected WebSockets are not returned by this method, but `getWebSockets` may still return websockets even after `ws.close` has been called. For example, if the server-side WebSocket sends a close, but does not receive one back (and has not detected a disconnect from the client), then the connection is in the CLOSING 'readyState'. The client might send more messages, so the WebSocket is technically not disconnected.
+Disconnected WebSockets are not returned by this method, but `getWebSockets` may still return WebSockets even after `ws.close` has been called. For example, if the server-side WebSocket sends a close, but does not receive one back (and has not detected a disconnect from the client), then the connection is in the CLOSING 'readyState'. The client might send more messages, so the WebSocket is technically not disconnected.
 
 :::
 
@@ -141,7 +141,7 @@ Disconnected WebSockets are not returned by this method, but `getWebSockets` may
 
 #### Return values
 
-- An `Array<WebSocket>`
+- An `Array<WebSocket>`.
 
 ### `setWebSocketAutoResponse`
 
@@ -153,7 +153,7 @@ Disconnected WebSockets are not returned by this method, but `getWebSockets` may
 
 #### Parameters
 
-- An optional `WebSocketRequestResponsePair(request string, response string)` enabling any WebSocket accepted via [`DurableObjectState::acceptWebSocket`](/durable-objects/api/state/#acceptwebsocket) to automatically reply to the provided response when it receives the provided request. Both request and response are limited to 2,048 characters each. If the parameter is omitted any previously set auto-response configuration will be removed. [`DurableObjectState::getWebSocketAutoResponseTimestamp`](/durable-objects/api/state/#getwebsocketautoresponsetimestamp) will still reflect the last timestamp that an auto-response was sent.
+- An optional `WebSocketRequestResponsePair(request string, response string)` enabling any WebSocket accepted via [`DurableObjectState::acceptWebSocket`](/durable-objects/api/state/#acceptwebsocket) to automatically reply to the provided response when it receives the provided request. Both request and response are limited to 2,048 characters each. If the parameter is omitted, any previously set auto-response configuration will be removed. [`DurableObjectState::getWebSocketAutoResponseTimestamp`](/durable-objects/api/state/#getwebsocketautoresponsetimestamp) will still reflect the last timestamp that an auto-response was sent.
 
 #### Return values
 
@@ -175,7 +175,7 @@ Disconnected WebSockets are not returned by this method, but `getWebSockets` may
 
 #### Return values
 
-- A `WebSocketRequestResponsePair` or null
+- A `WebSocketRequestResponsePair` or null.
 
 ### `getWebSocketAutoResponseTimestamp`
 
@@ -219,7 +219,7 @@ If no parameter or a parameter of `0` is provided and a timeout has been previou
 
 #### Return values
 
-- A number or null if the timeout has not been set.
+- A number, or null if the timeout has not been set.
 
 ### `getTags`
 

src/content/docs/durable-objects/api/websockets.mdx

@@ -144,11 +144,7 @@ To learn more about WebSocket Hibernation, refer to [Build a WebSocket server wi
 
 ### webSocketMessage
 
-- <code>
-  	webSocketMessage(ws <Type text="WebSocket" />, message{" "}
-  	<Type text="string | ArrayBuffer" />)
-  </code>
-  : <Type text="void" />
+- <code> webSocketMessage(ws <Type text="WebSocket" />, message{" "} <Type text="string | ArrayBuffer" />)</code>: <Type text="void" />
 
   - Called by the system when an accepted WebSocket receives a message.
 
@@ -158,21 +154,15 @@ To learn more about WebSocket Hibernation, refer to [Build a WebSocket server wi
 
 ### webSocketClose
 
-- <code>
-  	webSocketClose(ws <Type text="WebSocket" />, code <Type text="number" />,
-  	reason <Type text="string" />, wasClean <Type text="boolean" />)
-  </code>
-  : <Type text="void" />
+- <code> webSocketClose(ws <Type text="WebSocket" />, code <Type text="number" />,reason <Type text="string" />, wasClean <Type text="boolean" />)</code>: <Type text="void" />
 
   - Called by the system when a WebSocket is closed. `wasClean()` is true if the connection closed cleanly, false otherwise.
 
   - This method can be `async`.
 
 ### webSocketError
 
-- <code>
-  	webSocketError(ws <Type text="WebSocket" />, error <Type text="any" />)
-  </code> : <Type text="void" />
+- <code> webSocketError(ws <Type text="WebSocket" />, error <Type text="any" />)</code> : <Type text="void" />
 
   - Called by the system when any non-disconnection related errors occur.
 

src/content/glossary/durable-objects.yaml

@@ -5,29 +5,29 @@ entries:
   general_definition: |-
     The product name, or the collective noun referring to more than one Durable Object instance.
 
-- term: "Namespace"
+- term: "namespace"
   general_definition: |-
-    A container for a collection of Durable Objects that all share the same Durable Object (class) definition. A single Namespace can have (tens of) millions of Durable Objects. Metrics are scoped per Namespace.
+    A container for a collection of Durable Objects that all share the same Durable Object (class) definition. A single namespace can have (tens of) millions of Durable Objects. Metrics are scoped per namespace.
 
 - term: "Durable Object"
   general_definition: |-
-    An individual Durable Object. A Durable Object is globally unique (referenced by ID), provides a global point of coordination for all methods/requests sent to it, and has private, persistent storage that is not shared with other Durable Objects within a Namespace.
+    An individual instance of a Durable Object class. A Durable Object is globally unique (referenced by ID), provides a global point of coordination for all methods/requests sent to it, and has private, persistent storage that is not shared with other Durable Objects within a namespace.
 
-- term: "Stub"
+- term: "stub"
   general_definition: |-
-    An object that refers to a unique Durable Object within a Namespace and allows you to call into that Durable Object via RPC methods or the `fetch` API. For example, `let stub = env.MY_DURABLE_OBJECT.get(id)`
+    An object that refers to a unique Durable Object within a namespace and allows you to call into that Durable Object via RPC methods or the `fetch` API. For example, `let stub = env.MY_DURABLE_OBJECT.get(id)`
 
 - term: "actor"
   general_definition: |-
-    A term referring to a unique Durable Object.
+    A term referring to a unique Durable Object. See "Durable Object".
 
 - term: "instance"
   general_definition: |-
-    See 'actor'.
+    See "actor".
 
 - term: "Durable Object class"
   general_definition: |-
-    The JavaScript class that defines the methods (RPC) and handlers (`fetch`, `alarm`) as part of your Durable Object, and/or an optional `constructor`. All Durable Objects within a single Namespace share the same class definition.
+    The JavaScript class that defines the methods (RPC) and handlers (`fetch`, `alarm`) as part of your Durable Object, and/or an optional `constructor`. All Durable Objects within a single namespace share the same class definition.
 
 - term: "Storage Backend"
   general_definition: |-
@@ -50,7 +50,7 @@ entries:
   general_definition: |-
     API methods part of Storage API that support SQL querying.
 
-- term: Migration
+- term: "migration"
   general_definition: |-
     A Durable Object migration is a mapping process from a class name to a runtime state.
     Initiate a Durable Object migration when you need to:
@@ -60,6 +60,10 @@ entries:
     - Delete a Durable Object class.
     - Transfer an existing Durable Objects class.
 
-- term: Alarm
+- term: "alarm"
   general_definition: |-
     A Durable Object alarm is a mechanism that allows you to schedule the Durable Object to be woken up at a time in the future.
+
+- term: "event context"
+  general_definition: |-
+    The duration for which a Durable Object is kept in memory.