From b0e067e4ae9669f16e03e0874a30ae3b94bb111d Mon Sep 17 00:00:00 2001
From: KernelDeimos <eric.alex.dube@gmail.com>
Date: Sun, 23 Jun 2024 17:35:19 -0400
Subject: [PATCH] doc: misc doc additions

---
 doc/uncategorized/README.md     |  9 +++++
 doc/uncategorized/es6-note.md   | 46 +++++++++++++++++++++++
 doc/uncategorized/puter-mods.md | 66 +++++++++++++++++++++++++++++++++
 3 files changed, 121 insertions(+)
 create mode 100644 doc/uncategorized/README.md
 create mode 100644 doc/uncategorized/es6-note.md
 create mode 100644 doc/uncategorized/puter-mods.md

diff --git a/doc/uncategorized/README.md b/doc/uncategorized/README.md
new file mode 100644
index 00000000..d6f07218
--- /dev/null
+++ b/doc/uncategorized/README.md
@@ -0,0 +1,9 @@
+# Uncategorized Documentation
+
+Any document in this directory may be moved in the future to
+a more suitable location. This is a good place to put any
+documentation that needs to be written when it's unclear what
+the best place for it is. This is to avoid situations where
+documentation _doesn't_ get written simply because it's not clear
+where it belongs (something which the author of this very document
+has been guilty of at times).
diff --git a/doc/uncategorized/es6-note.md b/doc/uncategorized/es6-note.md
new file mode 100644
index 00000000..3bbb050a
--- /dev/null
+++ b/doc/uncategorized/es6-note.md
@@ -0,0 +1,46 @@
+# Notes about ES6 Class Syntax
+
+## Document Meta
+
+> **backend focus:** This documentation is more relevant to
+> Puter's backend than frontend, but is placed here because
+> it could apply to other areas in the future.
+
+## Expressions as Methods
+
+One important shortcoming in the ES6 class syntax to be aware of
+is that it discourages the use of expressions as methods.
+
+For example:
+
+```javascript
+class ExampleClass extends SomeBase {
+    intuitive_method_definition () {}
+    
+    constructor () {
+        this.less_intuitive = some_expr();
+    }
+}
+```
+
+Even if it is known that the return type of `some_expr` is a function,
+it is still unclear whether it's being used as a callback or
+as a method without other context in the code, since this is
+how we typically assign instance members rather than methods.
+
+We solve this in Puter's backend using a **trait** called
+[AssignableMethodsTrait](../../packages/backend/src/traits/AssignableMethodsTrait.js)
+which allows a static member called `METHODS` to contain
+method definitions.
+
+### Uses for Expressions as Methods
+
+#### Method Composition
+
+Method Composition is the act of composing methods from other
+constituents. For example,
+[Sequence](../../packages/backend/src/codex/Sequence.js)
+allows composing a method from smaller functions, allowing
+easier definition of "in-betwewen-each" behaviors and ways
+to track which values from the arguments are actually read
+during a particular call.
diff --git a/doc/uncategorized/puter-mods.md b/doc/uncategorized/puter-mods.md
new file mode 100644
index 00000000..271d5e99
--- /dev/null
+++ b/doc/uncategorized/puter-mods.md
@@ -0,0 +1,66 @@
+# Puter Mods
+
+## What is a Puter Mod?
+
+Currently, the definition of a Puter mod is:
+
+> A [Module](../../packages/backend/doc/contributors/modules.md)
+> which is exported by a package directory which itself exists
+> within a directory specified in the `mod_directories` array
+> in `config.json`.
+
+## Enabling Puter Mods
+
+### Step 1: Update Configuration
+
+First update the configuration (usually at `./volatile/config.json`
+or `/var/puter/config.json`) to specify mod directories.
+
+```json
+{
+    "config_name": "example config",
+
+    "mod_directories": [
+        "{source}/mods/mods_enabled"
+    ]
+
+    // ... other config options
+}
+```
+
+The first path you'll want to add is
+`"{source}/mods/mods_enabled"`
+which adds all the mods included in Puter's official repository.
+You don't need to change `{source}` unless your entry javascript
+file is in a different location than the default.
+
+If you want to enable all the mods, you can change the path above
+to `mods_available` instead and skip step 2 below.
+
+### Step 2: Select Mods
+
+To enable a Puter mod, create a symbolic link (AKA symlink) in
+`mods/mods_enabled`, pointing to
+a directory in `mods/mods_available`. This follows the same convention
+as managing sites/mods in Apache or Nginx servers.
+
+For example to enable KDMOD (which you can read as "Kernel Dev" mod,
+or "the mod that GitHub user KernelDeimos created to help with testing")
+you would run this command:
+```sh
+ln -rs ./mods/mods_available/kdmod ./mods/mods_enabled/
+```
+
+This will create a symlink at `./mods/mods_enabled/kdmod` pointing
+to the directory `./mods/mods_available/kdmod`.
+
+> **note:** here are some helpful tips for the `ln` command:
+> - You can remember `ln`'s first argument is the unaffected
+>   source file by remembering `cp` and `mv` are the same in
+>   this way.
+> - If you don't add `-s` you get a hard link. You will rarely
+>   find yourself needing to do that.
+> - The `-r` flag allows you to write both paths relative to
+>   the directory from which you are calling the command, which
+>   is sometimes more intuitive.
+