Added documentation

packages/solid/src/requester/requests/deleteResource.ts

@@ -7,6 +7,8 @@ import { UnexpectedHttpError } from "../results/error/HttpErrorResult";
 import { HttpErrorResult } from "../results/error/HttpErrorResult";
 import type { DeleteSuccess } from "../results/success/DeleteSuccess";
 import type { DatasetRequestOptions } from "./requestOptions";
+import type { IBulkEditableDataset } from "@ldo/subscribable-dataset";
+import type { Quad } from "@rdfjs/types";
 
 /**
  * All possible return values for deleteResource
@@ -62,7 +64,8 @@ export async function deleteResource(
     // if it hasn't been deleted when you're unauthenticated. 404 happens when
     // the document never existed
     if (response.status === 205 || response.status === 404) {
-      updateDatasetOnSuccessfulDelete(uri, response.status === 205, options);
+      if (options?.dataset)
+        updateDatasetOnSuccessfulDelete(uri, options.dataset);
       return {
         isError: false,
         type: "deleteSuccess",
@@ -77,20 +80,16 @@ export async function deleteResource(
 }
 
 /**
- * TODO
+ * Assuming a successful delete has just been performed, this function updates
+ * datastores to reflect that.
+ *
+ * @param uri - The uri of the resouce that was removed
+ * @param dataset - The dataset that should be updated
  */
 export function updateDatasetOnSuccessfulDelete(
   uri: string,
-  resourceExisted: boolean,
-  options?: DatasetRequestOptions,
+  dataset: IBulkEditableDataset<Quad>,
 ): void {
-  if (options?.dataset) {
-    options.dataset.deleteMatches(
-      undefined,
-      undefined,
-      undefined,
-      namedNode(uri),
-    );
-    deleteResourceRdfFromContainer(uri, options.dataset);
-  }
+  dataset.deleteMatches(undefined, undefined, undefined, namedNode(uri));
+  deleteResourceRdfFromContainer(uri, dataset);
 }

packages/solid/src/resource/Resource.ts

@@ -729,7 +729,33 @@ export abstract class Resource extends (EventEmitter as new () => TypedEmitter<{
    */
 
   /**
-   * TODO
+   * Activates Websocket subscriptions on this resource. Updates, deletions,
+   * and creations on this resource will be tracked and all changes will be
+   * relected in LDO's resources and graph.
+   *
+   * @param onNotificationError - A callback function if there is an error
+   * with notifications.
+   * @returns OpenSubscriptionResult
+   *
+   * @example
+   * ```typescript
+   * const resource = solidLdoDataset
+   *   .getResource("https://example.com/spiderman");
+   * // A listener for if anything about spiderman in the global dataset is
+   * // changed. Note that this will also listen for any local changes as well
+   * // as changes to remote resources to which you have notification
+   * // subscriptions enabled.
+   * solidLdoDataset.addListener(
+   *   [namedNode("https://example.com/spiderman#spiderman"), null, null, null],
+   *   () => {
+   *     // Triggers when the file changes on the Pod or locally
+   *     console.log("Something changed about SpiderMan");
+   *   },
+   * );
+   *
+   * // Subscribe
+   * const subscriptionResult = await testContainer.subscribeToNotifications();
+   * // ... From there you can ait for a file to be changed on the Pod.
    */
   async subscribeToNotifications(
     onNotificationError?: (err: Error) => void,
@@ -745,7 +771,7 @@ export abstract class Resource extends (EventEmitter as new () => TypedEmitter<{
 
   /**
    * @internal
-   * TODO
+   * Function that triggers whenever a notification is recieved.
    */
   protected async onNotification(message: NotificationMessage): Promise<void> {
     const objectResource = this.context.solidLdoDataset.getResource(
@@ -759,9 +785,10 @@ export abstract class Resource extends (EventEmitter as new () => TypedEmitter<{
       case "Delete":
       case "Remove":
         // Delete the resource without have to make an additional read request
-        updateDatasetOnSuccessfulDelete(message.object, true, {
-          dataset: this.context.solidLdoDataset,
-        });
+        updateDatasetOnSuccessfulDelete(
+          message.object,
+          this.context.solidLdoDataset,
+        );
         objectResource.updateWithDeleteSuccess({
           type: "deleteSuccess",
           isError: false,
@@ -773,7 +800,14 @@ export abstract class Resource extends (EventEmitter as new () => TypedEmitter<{
   }
 
   /**
-   * TODO
+   * Unsubscribes from changes made to this resource on the Pod
+   *
+   * @returns CloseSubscriptionResult
+   *
+   * @example
+   * ```typescript
+   * resource.unsubscribeFromNotifications()
+   * ```
    */
   async unsubscribeFromNotifications(): Promise<CloseSubscriptionResult> {
     const result = await this.notificationSubscription?.close();

packages/solid/src/resource/notifications/NotificationMessage.ts

@@ -1,3 +1,6 @@
+/**
+ * A message sent from the Pod as a notification
+ */
 export interface NotificationMessage {
   "@context": string | string[];
   id: string;

packages/solid/src/resource/notifications/NotificationSubscription.ts

@@ -15,6 +15,10 @@ export type CloseSubscriptionResult =
   | UnsubscribeToNotificationSuccess
   | UnexpectedResourceError;
 
+/**
+ * @internal
+ * Abstract class for notification subscription methods.
+ */
 export abstract class NotificationSubscription {
   protected resource: Resource;
   protected onNotification: (message: NotificationMessage) => void;
@@ -33,6 +37,15 @@ export abstract class NotificationSubscription {
     this.context = context;
   }
 
+  /**
+   * @internal
+   * Opens the subscription
+   */
   abstract open(): Promise<OpenSubscriptionResult>;
+
+  /**
+   * @internal
+   * Closes the subscription
+   */
   abstract close(): Promise<CloseSubscriptionResult>;
 }

packages/solid/src/resource/notifications/results/NotificationErrors.ts

@@ -1,5 +1,9 @@
 import { ResourceError } from "../../../requester/results/error/ErrorResult";
 
+/**
+ * Indicates that the requested method for receiving notifications is not
+ * supported by this Pod.
+ */
 export class UnsupportedNotificationError extends ResourceError {
   readonly type = "unsupportedNotificationError" as const;
 }