From 73f738c9d924d78ecebd8f139d2038daf05876da Mon Sep 17 00:00:00 2001
From: KernelDeimos <eric.alex.dube@gmail.com>
Date: Fri, 6 Dec 2024 13:29:50 -0500
Subject: [PATCH] doc: add more extensions documentation

---
 doc/contributors/extensions.md      |  5 +++--
 doc/contributors/vscode.md          |  2 ++
 src/backend/src/Extension.js        | 26 ++++++++++++++++++++++++++
 src/backend/src/ExtensionService.js |  5 +++++
 4 files changed, 36 insertions(+), 2 deletions(-)
 create mode 100644 doc/contributors/vscode.md

diff --git a/doc/contributors/extensions.md b/doc/contributors/extensions.md
index 12cd44d6..e95570e6 100644
--- a/doc/contributors/extensions.md
+++ b/doc/contributors/extensions.md
@@ -1,2 +1,3 @@
-### `vscode`
-- `es6-string-html`
+## Puter Extensions
+
+See the [Wiki Page](https://github.com/HeyPuter/puter/wiki/ex_extensions)
diff --git a/doc/contributors/vscode.md b/doc/contributors/vscode.md
new file mode 100644
index 00000000..12cd44d6
--- /dev/null
+++ b/doc/contributors/vscode.md
@@ -0,0 +1,2 @@
+### `vscode`
+- `es6-string-html`
diff --git a/src/backend/src/Extension.js b/src/backend/src/Extension.js
index 6b2d4ade..e3601d2b 100644
--- a/src/backend/src/Extension.js
+++ b/src/backend/src/Extension.js
@@ -3,6 +3,10 @@ const EmitterFeature = require("@heyputer/putility/src/features/EmitterFeature")
 const { Context } = require("./util/context");
 const { ExtensionServiceState } = require("./ExtensionService");
 
+/**
+ * This class creates the `extension` global that is seem by Puter backend
+ * extensions.
+ */
 class Extension extends AdvancedBase {
     static FEATURES = [
         EmitterFeature({
@@ -24,6 +28,9 @@ class Extension extends AdvancedBase {
         console.log('Example method called by an extension.');
     }
 
+    /**
+     * This will get a database instance from the default service.
+     */
     get db () {
         const db = this.service.values.get('db');
         if ( ! db ) {
@@ -35,6 +42,12 @@ class Extension extends AdvancedBase {
         return db;
     }
 
+    /**
+     * This will create a GET endpoint on the default service.
+     * @param {*} path - route for the endpoint
+     * @param {*} handler - function to handle the endpoint
+     * @param {*} options - options like noauth (bool) and mw (array)
+     */
     get (path, handler, options) {
         // this extension will have a default service
         this.ensure_service_();
@@ -51,6 +64,12 @@ class Extension extends AdvancedBase {
         });
     }
 
+    /**
+     * This will create a POST endpoint on the default service.
+     * @param {*} path - route for the endpoint
+     * @param {*} handler - function to handle the endpoint
+     * @param {*} options - options like noauth (bool) and mw (array)
+     */
     post (path, handler, options) {
         // this extension will have a default service
         this.ensure_service_();
@@ -67,6 +86,13 @@ class Extension extends AdvancedBase {
         });
     }
 
+    /**
+     * This method will create the "default service" for an extension.
+     * This is specifically for Puter extensions that do not define their
+     * own service classes.
+     * 
+     * @returns {void}
+     */
     ensure_service_ () {
         if ( this.service ) {
             return;
diff --git a/src/backend/src/ExtensionService.js b/src/backend/src/ExtensionService.js
index 7ea96d12..43705388 100644
--- a/src/backend/src/ExtensionService.js
+++ b/src/backend/src/ExtensionService.js
@@ -5,6 +5,11 @@ const configurable_auth = require("./middleware/configurable_auth");
 const { Context } = require("./util/context");
 const { DB_READ, DB_WRITE } = require("./services/database/consts");
 
+/**
+ * State shared with the default service and the `extension` global so that
+ * methods on `extension` can register routes (and make other changes in the
+ * future) to the default service.
+ */
 class ExtensionServiceState extends AdvancedBase {
     constructor (...a) {
         super(...a);