diff --git a/.github/workflows/codecov.yml b/.github/workflows/codecov.yml
index dcdf7910..9bece0f6 100644
--- a/.github/workflows/codecov.yml
+++ b/.github/workflows/codecov.yml
@@ -35,4 +35,3 @@ jobs:
         uses: codecov/test-results-action@v1
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
-
diff --git a/src/lib/components/color-picker/color-picker.svelte b/src/lib/components/color-picker/color-picker.svelte
index 793730cf..6d479b39 100644
--- a/src/lib/components/color-picker/color-picker.svelte
+++ b/src/lib/components/color-picker/color-picker.svelte
@@ -1,3 +1,21 @@
+<!--
+# Color Picker component
+
+Provides input for the Color type.
+The user can either choose from a pre-defined palette or use the system color picker.
+The latter only works in browser that support the HTML5 color input type.
+
+Props:
+- `color` (required): The currently selected color. Can be used with `bind`.
+- `options`: An array of [Color, string] pairs, where the string is a human-readable name for the color (e.g. "Cyan").
+             This is the pre-defined palette. Defaults to a list of 8 colors based on Tailwind CSS defaults.
+- `onSelect`: A callback function that is called when a color is selected.
+- `class`: String of additional Tailwind CSS classes to add to the top-level div.
+
+See also: 
+- https://www.npmjs.com/package/color
+- https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/color
+-->
 <!--suppress ES6UnusedImports -->
 <script lang="ts">
   import { Button } from "$lib/components/ui/button";
diff --git a/src/lib/components/combobox/combobox.svelte b/src/lib/components/combobox/combobox.svelte
index d7ba8149..93838160 100644
--- a/src/lib/components/combobox/combobox.svelte
+++ b/src/lib/components/combobox/combobox.svelte
@@ -1,3 +1,31 @@
+<!--
+# Generic Combobox Component
+
+This is a generic combobox (i.e. Select with a built-in search) that is used to pick ONE item from a list.
+The items can be any type, but to make it work you must supply your own functions to:
+- Provide a human-friendly name (and, optionally, a picture, icon, and/or description tooltip) for each item. (`display`)
+- Generate a unique ID for each item (can be any string, as long as it is unique and consistent). (`getId`)
+
+By default, the item ID is used to compare items (needed to mark the currently selected item with a checkmark).
+You can override `eq` with your own implementation. Idk why you would want to do that, but the option is there.
+
+## Props:
+- `options` (required): The list of items to choose from. Can be any type T.
+- `display` (required): A function that takes an option (`T` or `undefined`) and returns a `Display` object.
+- `getId` (required): A function that takes an option (`T`) and returns a string ID for that option.
+- `eq`: A function that takes two options (`T` or `undefined`) and returns true if they are equal. Default: calls `getId` on both and compares the results.
+- `value`: The currently selected item. Must be type `T` or `undefined` (meaning no item is selected). Bindable; Defaults to `undefined` (no item selected).
+- `open`: Whether the combobox is open or closed. Bindable; Defaults to `false` (closed).
+- `onChange`: A callback that fires when the selected item changes. Takes the old and new values as arguments. Defaults to a no-op.
+- `onSelect`: A callback that fires when the user selects an item. Takes the new value as an argument. Defaults to a no-op.
+- `allowUnselect`: If true, the user can unselect the currently selected item (i.e. set it to `undefined`). Defaults to true.
+- `closeOnSelect`: If true, the combobox will close when the user selects an item. Defaults to true.
+- `placeholder`: A string to show when no item is selected. Defaults to "Select an item".
+- `class`: A string of additional Tailwind CSS classes to add to the top-level div.
+
+See also:
+- $lib/ui/Display - the Display interface definition
+-->
 <!--suppress ES6UnusedImports -->
 <script lang="ts" generics="T">
   import { Button } from "$lib/components/ui/button";
@@ -23,7 +51,7 @@
   export let allowUnselect = true;
   export let closeOnSelect = true;
   export let value: T | undefined = undefined;
-  export let placeholder: string | undefined = undefined;
+  export let placeholder = "Select an item";
   export let options: T[] = [];
   let className = "";
 
diff --git a/src/lib/components/corner-highlight/corner-highlight.svelte b/src/lib/components/corner-highlight/corner-highlight.svelte
index a77383b1..daed3b85 100644
--- a/src/lib/components/corner-highlight/corner-highlight.svelte
+++ b/src/lib/components/corner-highlight/corner-highlight.svelte
@@ -1,3 +1,18 @@
+<!--
+# Color Highlight Component
+
+Helper component that wraps the given content in a rectangular div with one corner highlighted by a colored triangle.
+Designed for use inside of tables, cards, or similar.
+
+## Props:
+- `highlightColor`: The color of the highlight. Can be a string or a Color object. Defaults to "#ff3e00" (orange).
+- `cornerSize`: Size of the corner highlight. Can be a CSS string (e.g. "30px", "2rem") or a number (e.g. 30 - equivalent to "30px"). Defaults to "30px".
+- `cornerOpacity`: Opacity of the corner highlight. Defaults to 1 (fully opaque).
+- `position`: Which corner to highlight. Defaults to `top-left`.
+- `contentClass`: Additional Tailwind classes to apply to the content area.
+- `class`: Additional Tailwind classes to apply to the container.
+-->
+
 <script lang="ts">
   import Color from "color";
 
@@ -40,26 +55,11 @@
 
     switch (position) {
       case "top-left":
-        return {
-          ...baseStyles,
-          top: 0,
-          left: 0,
-          clipPath: "polygon(0 0, 100% 0, 0 100%)",
-        };
+        return { ...baseStyles, top: 0, left: 0, clipPath: "polygon(0 0, 100% 0, 0 100%)" };
       case "top-right":
-        return {
-          ...baseStyles,
-          top: 0,
-          right: 0,
-          clipPath: "polygon(100% 0, 0 0, 100% 100%)",
-        };
+        return { ...baseStyles, top: 0, right: 0, clipPath: "polygon(100% 0, 0 0, 100% 100%)" };
       case "bottom-left":
-        return {
-          ...baseStyles,
-          bottom: 0,
-          left: 0,
-          clipPath: "polygon(0 100%, 100% 100%, 0 0)",
-        };
+        return { ...baseStyles, bottom: 0, left: 0, clipPath: "polygon(0 100%, 100% 100%, 0 0)" };
       case "bottom-right":
         return {
           ...baseStyles,
@@ -68,12 +68,7 @@
           clipPath: "polygon(100% 100%, 100% 0, 0 100%)",
         };
       default:
-        return {
-          ...baseStyles,
-          top: 0,
-          left: 0,
-          clipPath: "polygon(0 0, 100% 0, 0 100%)",
-        };
+        return { ...baseStyles, top: 0, left: 0, clipPath: "polygon(0 0, 100% 0, 0 100%)" };
     }
   }
 
diff --git a/src/lib/components/data-table/README.md b/src/lib/components/data-table/README.md
new file mode 100644
index 00000000..e111299b
--- /dev/null
+++ b/src/lib/components/data-table/README.md
@@ -0,0 +1,48 @@
+This directory contains a wrapper over the `shadcn-svelte` [Data Table](https://www.shadcn-svelte.com/docs/components/data-table) component,
+which, in turn, wraps [Svelte Headless Table](https://svelte-headless-table.bryanmylee.com/).
+
+The underlying component is "headless" (i.e. provides the underlying logic without display), and we define the styling here.
+We also set up the "plugins" (e.g. search, sorting, pagination) and define columns for data types used in this project.
+
+The base logic is in `core`, utilities are in `lib` and concrete implementations are here (e.g. `person-data-table.svelte`).
+
+Thanks to the headless component, we can easily define columns in a JSON format:
+
+```typescript
+let columnInitializers: ColumnInitializer<Shift>[] = [
+  {
+    accessor: (row) => row as Display,
+    cell: (cell) => createRender(ProfilePicture, { item: cell.value }),
+    header: "Icon",
+    id: "icon",
+    plugins: {
+      sort: {
+        disable: true,
+      },
+    },
+  },
+  {
+    accessor: (row: Person) => dobFormatter.format(row.dob),
+    header: "Date of Birth",
+    id: "dob",
+  },
+  ...
+]
+```
+
+And provide a dropdown of actions for each row (e.g. editing or deleting the underlying entry):
+
+```typescript
+let actions = new Map([
+  ["Edit", rowClick],
+  ["Delete", rowDelete],
+]);
+function rowDelete(item: Person) {
+  // do something on click!
+}
+```
+
+And everything else is handled for us by the library and the `core` implementation!
+
+This reduces the complexity and boilerplate required to write proper data tables.
+Data tables are used widely in the project. If you are looking to build a new one, I would suggest copying one of the existing implementations and editing the columns / row actions.
diff --git a/src/lib/components/data-table/core/actions-btn.svelte b/src/lib/components/data-table/core/actions-btn.svelte
index 8c612cce..80bf4356 100644
--- a/src/lib/components/data-table/core/actions-btn.svelte
+++ b/src/lib/components/data-table/core/actions-btn.svelte
@@ -1,3 +1,10 @@
+<!--
+Dropdown menu that is displayed at the end of each row.
+
+Props:
+- `item`: The item this row represents.
+- `actions`: A map of human-readable names to functions that take the item as an argument.
+-->
 <!--suppress ES6UnusedImports -->
 <script lang="ts" generics="T">
   import { Button } from "$lib/components/ui/button";
diff --git a/src/lib/components/data-table/core/data-table.svelte b/src/lib/components/data-table/core/data-table.svelte
index b61c84b9..717e78f4 100644
--- a/src/lib/components/data-table/core/data-table.svelte
+++ b/src/lib/components/data-table/core/data-table.svelte
@@ -1,8 +1,87 @@
-<!-- Need this due to the way the svelte-headless-table library is written -->
+<!--
+# Data Table (Base Component)
+
+Provides the basic styling and functionality for a data table. Wraps the `svelte-headless-table` library.
+
+## Props
+- `data`: A Svelte store containing a list of items to display in the table. Can be any type `T[]`.
+- `header`: True if there is a toolbar immediately above the table. Only used for styling.
+- `actions`: A map of human-readable names to functions that take the item as an argument. Used to create a dropdown menu at the end of each row.
+- `defaultAction`: A function that takes the item as an argument. Called when the user clicks on a row.
+- `columnInitializers`: An array of column initializers. See below for more details, and also check the `svelte-headless-table` docs.
+- `paginationConfig`: Pagination parameters (e.g. page size, initial page index, etc.). See `svelte-headless-table` docs for more details.
+- `sortByConfig`: Sort plugin config. Can be used to set some initial sort keys, among other things. See `svelte-headless-table` docs for more details.
+- `className`: Additional Tailwind CSS classes to add to the table.
+- `filterValue`: Svelte store containing the current search string; Used to filter table rows. Table updates reactively when this changes.
+- `hideForId`: An object with column IDs as keys and booleans as values. A column is hidden iff its ID is in the object and set to true.
+- `selectedDataIds`: Set of IDs of currently selected rows. Not currently used. See `svelte-headless-table` docs for more details.
+- `sortKeys`: State of the sort plugin, including a list of currently active sort keys. See `svelte-headless-table` docs for more details.
+- `flatColumns`: Column information generated by the library. Pass this to plugin functions and components that invoke them (or otherwise need to know about the columns).
+
+## Column Initializers
+
+Used to create columns in the table. Each column is given by an object in the form:
+
+```typescript
+{
+  accessor: (row: T) => any,                                                     // Function that takes an item and returns a value for this column.
+  cell: (cell: Cell<T>) => createRender(MyComponent, { item: cell.value, ... })  // Optional function to render an arbitrary component in the cell. See below.
+  header: "Name",                                                                // Human-readable name for the column.
+  id: "name",                                                                    // Unique ID for the column. Must be unique across all columns and used for sorting, filtering, etc.
+  plugins: { ... }                                                               // Extra plugin config for this column. See `svelte-headless-table` docs for more details.
+},
+```
+
+If the `accessor` function returns a primitive value (e.g. a string), it is displayed in the cell as-is.
+You can also provide a custom component to render in the cell instead. In this case, the `accessor` function can return any arbitrary value, which is accessible by the render function as `cell.value`.
+The render function takes a Svelte component and a props object to pass to it. Consider this (simplified) example:
+
+```typescript
+import { Input } from "$lib/components/ui/input";
+
+interface Person {
+  name: string;
+  age: number;
+}
+
+columnInitializers: ColumnInitializer<Person>[] = [
+  {
+    accessor: (row: Person) => row.name,                                                 
+    cell: (cell: Cell<Person>) => createRender(Input, { value: cell.value }),
+    header: "Name",                                                               
+    id: "name",        
+  },
+  ...
+]
+
+data = writable<Person[]>([
+  { name: "John Doe", age: 30 },
+  ...
+]);
+
+...
+```
+
+The equivalent of
+
+```svelte
+{#each data as person}
+  <Input value={person.name} />
+{/each}
+```
+
+will be rendered in the "Name" column of the table.
+
+## See also
+
+- [svelte-headless-table](https://svelte-headless-table.bryanmylee.com/)
+- [shadcn-svelte Data Table](https://www.shadcn-svelte.com/docs/components/data-table)
+-->
+
+<!-- Need `any` in some places due to the way the svelte-headless-table library is written -->
 <!-- eslint-disable  @typescript-eslint/no-explicit-any -->
 <script lang="ts" generics="T, V = any">
   import ActionsBtn from "./actions-btn.svelte";
-
   import { Button } from "$lib/components/ui/button";
   import * as Table from "$lib/components/ui/table";
   import { cn } from "$lib/utils/ui";
@@ -52,14 +131,7 @@
     cell: (cell) => createRender(ActionsBtn<T>, { actions, item: cell.value }),
     header: "Actions",
     id: "actions",
-    plugins: {
-      sort: {
-        disable: true,
-      },
-      tableFilter: {
-        disable: true,
-      },
-    },
+    plugins: { sort: { disable: true }, tableFilter: { disable: true } },
   };
   const colInits = [...columnInitializers, actionsCol];
   const columns = table.createColumns(colInits.map((col) => table.column(col)));
diff --git a/src/lib/components/data-table/core/index.ts b/src/lib/components/data-table/core/index.ts
index 591e779e..1b2ff8b8 100644
--- a/src/lib/components/data-table/core/index.ts
+++ b/src/lib/components/data-table/core/index.ts
@@ -3,7 +3,16 @@ import DataTableCore from "./data-table.svelte";
 
 /* eslint-disable  @typescript-eslint/no-explicit-any */
 
+/** Map of human-readable action names to their implementations (functions that take the row item and do something with it) */
 export type RowActions<T> = Map<string, (item: T) => void>;
+
+/**
+ * Some boilerplate for column initializers to allow some basic type inference
+ * - `T` is the row type
+ * - `V` is the cell value type (returned by the cell's accessor function)
+ * - Middle value is the plugin config but defining it properly is complicated and probably not worth it
+ */
 export type ColumnInitializer<T, V = any> = DataColumnInitBase<T, any, V> &
   DataColumnInitFnAndId<T, string, V>;
+
 export { DataTableCore };
diff --git a/src/lib/components/data-table/lib/column-hide-selector.svelte b/src/lib/components/data-table/lib/column-hide-selector.svelte
index 667b0978..b35a759a 100644
--- a/src/lib/components/data-table/lib/column-hide-selector.svelte
+++ b/src/lib/components/data-table/lib/column-hide-selector.svelte
@@ -1,3 +1,10 @@
+<!--
+Dropdown that allows the user to hide/show certain columns in a table.
+Props:
+- `flatColumns`: The table columns (see svelte-headless-table and the `data-table` component). 
+- `hideForId`: An object mapping column IDs to booleans (true = hidden). A column is hidden iff it is explicitly mapped to `true`.
+-->
+
 <script lang="ts">
   // We need to allow explicit any here because of the way the svelte-headless-table library is written
   /* eslint-disable  @typescript-eslint/no-explicit-any */
diff --git a/src/lib/components/data-table/lib/delete-dialog.svelte b/src/lib/components/data-table/lib/delete-dialog.svelte
index bdab50ad..01b19f26 100644
--- a/src/lib/components/data-table/lib/delete-dialog.svelte
+++ b/src/lib/components/data-table/lib/delete-dialog.svelte
@@ -1,3 +1,18 @@
+<!--
+# Delete Dialog Component
+
+Invoked when the user clicks "delete" in a row's actions menu.
+Displays a dialog asking the user to confirm deletion.
+Disabling `settings.askDeleteConfirmation` will skip it and delete the item immediately.
+
+Props:
+- `selected`: The item to delete. Must be a `Base` object. (See $lib/model/core for details.)
+- `open`: Whether the dialog is open or closed. Bindable; Defaults to `false` (closed).
+- `extraDescription`: A string to show under the main description. Defaults to an empty string.
+- `state`: The state containing the item. (See $lib/model for details.)
+- `onDelete`: A callback that fires when the user clicks "delete". Takes no arguments. Defaults to a no-op.
+-->
+
 <script lang="ts">
   import { Base } from "$lib/model/core";
   import { state as GLOBAL_STATE } from "$lib/model";
diff --git a/src/lib/components/data-table/lib/index.ts b/src/lib/components/data-table/lib/index.ts
index eb4b9b24..48a2cd9f 100644
--- a/src/lib/components/data-table/lib/index.ts
+++ b/src/lib/components/data-table/lib/index.ts
@@ -1,6 +1,10 @@
 import ColumnHideSelector from "./column-hide-selector.svelte";
 import TableHeader from "./table-header.svelte";
 
+/**
+ * Displays a capacity range (e.g. (2, 5, "shifts") -> "2 - 5 shifts").
+ * TODO: We should probably move this to the utils folder.
+ */
 export function mkCapacity(min?: number, max?: number, title?: string) {
   if (min) {
     if (max) {
diff --git a/src/lib/components/data-table/lib/table-header.svelte b/src/lib/components/data-table/lib/table-header.svelte
index 0a1169d8..aef25503 100644
--- a/src/lib/components/data-table/lib/table-header.svelte
+++ b/src/lib/components/data-table/lib/table-header.svelte
@@ -1,3 +1,7 @@
+<!--
+Helper component containing controls, displayed above a table.
+-->
+
 <script lang="ts">
   let sticky = true;
   export { sticky };
diff --git a/src/lib/components/data-table/location-data-table.svelte b/src/lib/components/data-table/location-data-table.svelte
index 300209fc..bbe71afd 100644
--- a/src/lib/components/data-table/location-data-table.svelte
+++ b/src/lib/components/data-table/location-data-table.svelte
@@ -1,3 +1,17 @@
+<!--
+# Location Data Table
+
+Data table for the Location data type.
+See also: `$lib/model/core/location.ts`.
+
+## Props:
+- `data`: Svelte store of `Location[]` to be displayed in the table.
+- `header`: If true, displays a map to visualise locations and a header with some controls.
+- `state`: The global state containing the locations.
+- `actions`: A map of `(<action name>, (item: Location) => void)`. By default, contains "Edit" (opens the edit dialog) and "Delete" (deletes the item).
+- `mapClass`: Tailwind CSS class for the map.
+- `class`: Extra Tailwind CSS classes to add to the table.
+-->
 <script lang="ts">
   import { EditDialog } from "$lib/components/edit-dialog";
   import { Map as MapComponent } from "$lib/components/map";
@@ -27,30 +41,23 @@
   let className = "";
   let mapClass = "h-[300px] w-full";
 
+  // Currently selected location
   let selected: Location | undefined = undefined;
+  // Dialog controls
   let alertOpen = false;
   let dialogOpen = false;
   let dialogTitle = "Edit Location";
+
+  // Column definitions
   let columnInitializers: ColumnInitializer<Location>[] = [
     {
       accessor: (row) => row as Display,
       cell: (cell) => createRender(ProfilePicture, { item: cell.value }),
       header: "Picture",
       id: "picture",
-      plugins: {
-        sort: {
-          disable: true,
-        },
-        tableFilter: {
-          disable: true,
-        },
-      },
-    },
-    {
-      accessor: (row: Location) => row.name,
-      header: "Name",
-      id: "name",
+      plugins: { sort: { disable: true }, tableFilter: { disable: true } },
     },
+    { accessor: (row: Location) => row.name, header: "Name", id: "name" },
     {
       accessor: (row: Location) =>
         row.point?.address.format(["street", "settlement", "country", "postcode"]) || "No Address",
@@ -69,6 +76,7 @@
     },
   ];
 
+  // Add extra columns for user-defined properties
   for (const prop of _get(state.templates).location.keys) {
     columnInitializers.push({
       accessor: (row: Location) => row.properties.get(prop),
@@ -112,9 +120,11 @@
 
 <div class="flex flex-col items-start justify-start {className}">
   {#if header}
+    <!-- Interactive map to show locations as points-->
     <MapComponent locations={$data} class="aspect-auto {mapClass}" onMarkerClick={markerClick} />
   {/if}
   <div class="mt-4 flex h-max w-full flex-col items-start justify-start overflow-y-scroll">
+    <!-- Table header with controls -->
     {#if header}
       <TableHeader sticky={true}>
         <svelte:fragment slot="start">
@@ -139,6 +149,7 @@
         </svelte:fragment>
       </TableHeader>
     {/if}
+    <!-- Data table -->
     <DataTableCore
       bind:filterValue
       bind:flatColumns
@@ -153,5 +164,6 @@
     />
   </div>
 </div>
+<!-- Edit and Delete pop-ups (initially closed) -->
 <EditDialog {selected} bind:open={dialogOpen} title={dialogTitle} />
 <DeleteDialog {selected} bind:open={alertOpen} />
diff --git a/src/lib/components/data-table/person-data-table.svelte b/src/lib/components/data-table/person-data-table.svelte
index 84339270..e0855b6b 100644
--- a/src/lib/components/data-table/person-data-table.svelte
+++ b/src/lib/components/data-table/person-data-table.svelte
@@ -1,3 +1,17 @@
+<!--
+# Person Data Table
+
+Data table for the Person data type.
+See also: `$lib/model/core/person.ts`.
+
+## Props:
+- `data`: Svelte store of `Person[]` to be displayed in the table.
+- `showHeader`: If true, displays a header with some controls.
+- `state`: The global state containing the objects.
+- `rowActions`: A map of EXTRA actions `(<action name>, (item: Person) => void)` on top of the default "Edit" and "Delete".
+
+TODO: Actions API should be made consistent with e.g. the `LocationDataTable` component.
+-->
 <script lang="ts">
   import { EditDialog } from "$lib/components/edit-dialog";
   import { ProfilePicture } from "$lib/components/profile";
@@ -25,36 +39,28 @@
 
   let flatColumns: FlatColumn<Person, any, string>[]; // eslint-disable-line @typescript-eslint/no-explicit-any
   let className = "";
+  // Dialog state / controls
   let selected: Person | undefined = undefined;
   let alertOpen = false;
   let dialogOpen = false;
   let dialogTitle = "Edit Person";
+  // Define format for date of birth
   const dobFormatter = new Intl.DateTimeFormat(navigator.language || "en", {
     day: "numeric",
     month: "short",
     year: "numeric",
   });
 
+  // Column definitions
   let columnInitializers: ColumnInitializer<Person>[] = [
     {
       accessor: (row) => row as Display,
       cell: (cell) => createRender(ProfilePicture, { item: cell.value }),
       header: "Avatar",
       id: "avatar",
-      plugins: {
-        sort: {
-          disable: true,
-        },
-        tableFilter: {
-          disable: true,
-        },
-      },
-    },
-    {
-      accessor: (row: Person) => row.name,
-      header: "Name",
-      id: "name",
+      plugins: { sort: { disable: true }, tableFilter: { disable: true } },
     },
+    { accessor: (row: Person) => row.name, header: "Name", id: "name" },
     {
       accessor: (row: Person) =>
         row.dob ? dobFormatter.format(row.dob.toDate(getLocalTimeZone())) : "Not Set",
@@ -63,6 +69,7 @@
     },
   ];
 
+  // Add columns for dynamic user-defined properties
   for (const prop of _get(state.templates).person.keys) {
     columnInitializers.push({
       accessor: (row: Person) => row.properties.get(prop),
@@ -72,6 +79,7 @@
     });
   }
 
+  // Row actions
   let actions = new Map([...rowActions, ["Edit", rowClick], ["Delete", rowDelete]]);
 
   function rowDelete(item: Person) {
diff --git a/src/lib/components/data-table/shift-data-table.svelte b/src/lib/components/data-table/shift-data-table.svelte
index deb00ed2..bbfff3e0 100644
--- a/src/lib/components/data-table/shift-data-table.svelte
+++ b/src/lib/components/data-table/shift-data-table.svelte
@@ -1,3 +1,16 @@
+<!--
+# Shift Data Table
+
+Data table for the Shift data type.
+See also: `$lib/model/core/shift.ts`.
+
+## Props:
+- `data`: Svelte store of `Shift[]` to be displayed in the table.
+- `showHeader`: If true, displays a header with some controls.
+- `state`: The global state containing the objects.
+- `actions`: A map of `(<action name>, (item: Shift) => void)`. By default, contains "Edit" (opens the edit dialog) and "Delete" (deletes the item).
+-->
+
 <script lang="ts">
   import { state as GLOBAL_STATE, Shift, State, Task } from "$lib/model";
   import type { Display } from "$lib/ui";
@@ -31,41 +44,19 @@
   let alertOpen = false;
   let dialogOpen = false;
   let dialogTitle = "Edit Person";
+
+  // Column definitions
   let columnInitializers: ColumnInitializer<Shift>[] = [
     {
       accessor: (row) => row as Display,
       cell: (cell) => createRender(ProfilePicture, { item: cell.value }),
       header: "Icon",
       id: "icon",
-      plugins: {
-        sort: {
-          disable: true,
-        },
-        tableFilter: {
-          disable: true,
-        },
-      },
-    },
-    {
-      accessor: (row: Shift) => row.name,
-      header: "Name",
-      id: "name",
-    },
-    {
-      accessor: (row: Shift) => row.fmtStartTime(),
-      header: "Start Time",
-      id: "timeStart",
-    },
-    {
-      accessor: (row: Shift) => row.fmtEndTime(),
-      header: "End Time",
-      id: "timeEnd",
+      plugins: { sort: { disable: true }, tableFilter: { disable: true } },
     },
-    // {
-    //   accessor: (row: Shift) => `${formattedDuration(row.duration)}`,
-    //   header: "Actual Duration",
-    //   id: "actualDuration",
-    // },
+    { accessor: (row: Shift) => row.name, header: "Name", id: "name" },
+    { accessor: (row: Shift) => row.fmtStartTime(), header: "Start Time", id: "timeStart" },
+    { accessor: (row: Shift) => row.fmtEndTime(), header: "End Time", id: "timeEnd" },
     {
       accessor: (row: Shift) => `${formattedDuration(row.paidDuration)}`,
       header: "Contracted Duration",
@@ -78,6 +69,9 @@
     },
   ];
 
+  // If the old ("granular") mode is used, display tasks in each shift.
+  // This requirement has been dropped: we now assign people to monolithic shifts without any speciific tasks.
+  // Keeping this code as it may be useful in the future.
   const settings = state.settings;
   if (_get(settings).assignmentMode === "granular") {
     columnInitializers.push({
@@ -86,16 +80,13 @@
       header: "Tasks in Shift",
       id: "tasks",
       plugins: {
-        sort: {
-          getSortValue: (value: Task[]) => value.map((t) => t.name).join(" "),
-        },
-        tableFilter: {
-          getFilterValue: (value: Task[]) => value.map((t) => t.name).join(" "),
-        },
+        sort: { getSortValue: (value: Task[]) => value.map((t) => t.name).join(" ") },
+        tableFilter: { getFilterValue: (value: Task[]) => value.map((t) => t.name).join(" ") },
       },
     });
   }
 
+  // Row action definitions
   let actions = new Map([...rowActions, ["Edit", rowClick], ["Delete", rowDelete]]);
 
   function rowDelete(item: Shift) {
diff --git a/src/lib/components/data-table/task-data-table.svelte b/src/lib/components/data-table/task-data-table.svelte
index 777c8426..692ab7ab 100644
--- a/src/lib/components/data-table/task-data-table.svelte
+++ b/src/lib/components/data-table/task-data-table.svelte
@@ -1,3 +1,9 @@
+<!--
+A data table for the `Task` model.
+This is currently not used anywhere as the "granular" mode has been dropped.
+The models have changed since and this component has not been tested. Keeping it in case we need it in the future.
+See also: `$lib/model/core/task.ts`.
+-->
 <script lang="ts">
   import { EditDialog } from "$lib/components/edit-dialog";
   import { ProfilePicture } from "$lib/components/profile";
@@ -34,20 +40,9 @@
       cell: (cell) => createRender(ProfilePicture, { item: cell.value }),
       header: "Picture",
       id: "picture",
-      plugins: {
-        sort: {
-          disable: true,
-        },
-        tableFilter: {
-          disable: true,
-        },
-      },
-    },
-    {
-      accessor: (row: Task) => row.name,
-      header: "Name",
-      id: "name",
+      plugins: { sort: { disable: true }, tableFilter: { disable: true } },
     },
+    { accessor: (row: Task) => row.name, header: "Name", id: "name" },
     {
       accessor: (row: Task) => mkCapacity(row.min.people, row.max.people, "people"),
       header: "Required Workers",
diff --git a/src/lib/components/date-picker/date-picker.svelte b/src/lib/components/date-picker/date-picker.svelte
index 83a62f98..35979b24 100644
--- a/src/lib/components/date-picker/date-picker.svelte
+++ b/src/lib/components/date-picker/date-picker.svelte
@@ -1,3 +1,25 @@
+<!--
+# Date Picker Component
+
+A dropdown with a calendar that allows the user to select a date.
+Currently selected date is shown in the button.
+Uses `@internationalized/date` for date handling.
+
+## Props
+- `value`: The currently selected date, or `undefined` for not selected.
+- `minValue`: The minimum date that can be selected.
+- `maxValue`: The maximum date that can be selected.
+- `placeholder`: Placeholder text when no date is selected.
+- `id`: ID for the button HTML element.
+- `class`: Additional Tailwind CSS classes for the button.
+- `onChange`: Callback function that is called when the date changes.
+- `disabled`: If true, the button is disabled and the calendar cannot be opened.
+
+See also:
+- https://www.npmjs.com/package/@internationalized/date
+- https://www.shadcn-svelte.com/docs/components/calendar
+- https://www.shadcn-svelte.com/docs/components/popover
+-->
 <!--suppress ES6UnusedImports -->
 <script lang="ts">
   import { Button } from "$lib/components/ui/button";
@@ -8,9 +30,7 @@
   import { type DateValue, DateFormatter, getLocalTimeZone } from "@internationalized/date";
   import CalendarIcon from "lucide-svelte/icons/calendar";
 
-  const df = new DateFormatter(navigator.language || "en-GB", {
-    dateStyle: "long",
-  });
+  const df = new DateFormatter(navigator.language || "en-GB", { dateStyle: "long" });
 
   const wkSt = weekStartsOn(navigator.language || "en-GB");
 
diff --git a/src/lib/components/date-picker/index.ts b/src/lib/components/date-picker/index.ts
index 6cba9aee..63351288 100644
--- a/src/lib/components/date-picker/index.ts
+++ b/src/lib/components/date-picker/index.ts
@@ -1,4 +1,6 @@
 import DatePicker from "./date-picker.svelte";
 import DateRangePicker from "./range-picker.svelte";
 
+// Dropdowns to pick a date or a range of dates
+
 export { DatePicker, DateRangePicker };
diff --git a/src/lib/components/date-picker/range-picker.svelte b/src/lib/components/date-picker/range-picker.svelte
index ff8fcb0f..416ba06c 100644
--- a/src/lib/components/date-picker/range-picker.svelte
+++ b/src/lib/components/date-picker/range-picker.svelte
@@ -1,3 +1,9 @@
+<!--
+# (Date) Range Picker Component
+
+A dropdown with a calendar that allows the user to select a date range (start - end).
+See also: `date-picker.svelte` - the APIs are essentially the same.
+-->
 <!--suppress ES6UnusedImports -->
 <script lang="ts">
   import { Button } from "$lib/components/ui/button";
diff --git a/src/lib/components/edit-dialog/display-edit-form.svelte b/src/lib/components/edit-dialog/display-edit-form.svelte
index 821b05fd..6d7397b8 100644
--- a/src/lib/components/edit-dialog/display-edit-form.svelte
+++ b/src/lib/components/edit-dialog/display-edit-form.svelte
@@ -1,3 +1,8 @@
+<!--
+Edit form for the basic fields of a `Display` object.
+Used inside edit dialogs for `Person`, `Location`, etc.
+See also: $lib/ui/Display.
+-->
 <script lang="ts">
   import { type Display } from "$lib/ui";
   import { ImagePicker } from "$lib/components/image-picker";
diff --git a/src/lib/components/edit-dialog/edit-assignment-pattern.svelte b/src/lib/components/edit-dialog/edit-assignment-pattern.svelte
index 5abce7f2..d777394c 100644
--- a/src/lib/components/edit-dialog/edit-assignment-pattern.svelte
+++ b/src/lib/components/edit-dialog/edit-assignment-pattern.svelte
@@ -1,3 +1,18 @@
+<!--
+# Assignment Pattern Edit Dialog
+
+Dialog for editing an `AssignmentPattern` object.
+An "assignment pattern" is a rule that assigns a person to a regular pattern of shifts (or days off) using an iCal-like recurrence rule.
+
+## Props
+- `item`: The `AssignmentPattern` object to edit.
+
+See also:
+- `$lib/model/temporal/recurrence.ts` for everything to do with recurrence rules.
+- `$lib/model/temporal/utils.ts` for a massive collection of date/time utility functions.
+- `$lib/model/core/assignment-pattern.ts` for the `AssignmentPattern` class.
+- https://github.com/jkbrzt/rrule for the underlying recurrence rule parser.
+-->
 <script lang="ts">
   import { AssignmentPattern } from "$lib/model";
   import RecurrenceOptionsEdit from "$lib/components/recurrence/recurrence_options_edit.svelte";
@@ -13,15 +28,9 @@
   function mkTypeSelect(pattern: AssignmentPattern) {
     switch (pattern.params.type) {
       case "DAY_OFF":
-        return {
-          value: "DAY_OFF",
-          label: "Day Off",
-        };
+        return { value: "DAY_OFF", label: "Day Off" };
       case "SHIFT":
-        return {
-          value: "SHIFT",
-          label: "Shift",
-        };
+        return { value: "SHIFT", label: "Shift" };
     }
   }
 
@@ -46,8 +55,10 @@
 
 <div class="gap- flex w-full flex-row gap-8">
   <div class="flex flex-col gap-5">
+    <!-- Everything in this element is Column # 1 -->
     <div class="flex w-full flex-col gap-1.5">
       <span class="text-sm font-semibold">Assignment Type</span>
+      <!-- Selector of Shift vs Day Off -->
       <Select.Root selected={mkTypeSelect(item)} onSelectedChange={onTypeChange}>
         <Select.Trigger class="max-w-48">
           <Select.Value placeholder="Select an assignment type" />
@@ -58,10 +69,12 @@
         </Select.Content>
       </Select.Root>
     </div>
+    <!-- Person selector -->
     <div class="flex w-full flex-col gap-1.5">
       <span class="text-sm font-semibold">Person</span>
       <Selector bind:value={item.person} options={$people} allowUnselect={false} variant="full" />
     </div>
+    <!-- If assigning to a shift, select a Shift -->
     {#if item.params.type === "SHIFT"}
       <div class="flex w-full flex-col gap-1.5">
         <span class="text-sm font-semibold">Shift</span>
@@ -69,6 +82,7 @@
       </div>
     {/if}
     <div class="flex w-full flex-col gap-1.5">
+      <!-- "Hard" assignment (must be respected) or "soft" (preference) -->
       <div class="flex w-full space-x-2">
         <Checkbox
           id="preference"
@@ -81,6 +95,7 @@
           >"Hard" assignment</Label
         >
       </div>
+      <!-- Generate a human-friendly description -->
       <p class="text-sm text-muted-foreground">
         {item.person?.name}
         {#if item.params.preference === "required"}
@@ -102,6 +117,7 @@
   </div>
   <Separator orientation="vertical" />
   <div class="flex flex-col gap-6" style="padding-top: 0.29rem;">
+    <!-- Column # 2 is the recurrence options form -->
     <RecurrenceOptionsEdit bind:recurrence={item.pattern.recurrenceOptions} />
   </div>
 </div>
diff --git a/src/lib/components/edit-dialog/edit-dialog.svelte b/src/lib/components/edit-dialog/edit-dialog.svelte
index 51508b9d..d9a8c4a3 100644
--- a/src/lib/components/edit-dialog/edit-dialog.svelte
+++ b/src/lib/components/edit-dialog/edit-dialog.svelte
@@ -1,3 +1,19 @@
+<!--
+Entry point for edit dialogs.
+
+- Content is defined in the `EditForm` component.
+- Default slot is the trigger button.
+- Named slots `options` and `actions` can be used to add extra options to the dialog.
+
+Props:
+- `selected`: The item being edited. For convenience, the component accepts `undefined` as well and displays an empty state.
+- `title`: The title of the dialog.
+- `open`: If true, the dialog is open. Bindable.
+- `state`: The global state containing the objects.
+- `onSubmit`: A callback that fires when the user submits the form. Takes the item as an argument.
+- `onOpenChange`: A callback that fires when the dialog is opened or closed. Argument is the new value of `open`.
+-->
+
 <script lang="ts" generics="T">
   import { Button } from "$lib/components/ui/button";
   import * as Dialog from "$lib/components/ui/dialog";
diff --git a/src/lib/components/edit-dialog/edit-form.svelte b/src/lib/components/edit-dialog/edit-form.svelte
index 40bce4b0..2d2bda6a 100644
--- a/src/lib/components/edit-dialog/edit-form.svelte
+++ b/src/lib/components/edit-dialog/edit-form.svelte
@@ -1,3 +1,9 @@
+<!--
+Edit form for (most) objects in our model.
+Accepts a generic value `T` and upcasts it to display the right edit fields.
+Used inside EditDialog.
+-->
+
 <script lang="ts" generics="T">
   import { DatePicker } from "$lib/components/date-picker";
   import PropertiesInput from "$lib/components/property/properties-input.svelte";
@@ -22,18 +28,22 @@
 <div
   class="mb-4 mt-4 flex h-full max-h-[60vh] w-full flex-col gap-6 overflow-y-scroll p-1 {className}"
 >
+  <!-- For all objects that implement `Display`, show a basic form (name / description / image) -->
   {#if isDisplay(item)}
     <DisplayEditForm bind:item />
   {/if}
+  <!-- For Person objects, show a DOB picker. Should be turned into a dynamic property in the future. -->
   {#if item instanceof Person}
     <div class="flex w-full flex-col gap-1.5">
       <Label class="font-semibold" for="birthday">Date of Birth</Label>
       <DatePicker id="birthday" class="w-full" bind:value={item.dob} />
     </div>
   {/if}
+  <!-- Display fields for user-defined dynamic properties -->
   {#if item instanceof WithProperties}
     <PropertiesInput properties={item.properties} />
   {/if}
+  <!-- Edit forms for specific data types (see corresponding files in this directory) -->
   {#if item instanceof Location}
     <EditLocation {item} locations={$locations} />
   {:else if item instanceof AssignmentPattern}
diff --git a/src/lib/components/edit-dialog/edit-location.svelte b/src/lib/components/edit-dialog/edit-location.svelte
index 3d7773fa..da9db3cc 100644
--- a/src/lib/components/edit-dialog/edit-location.svelte
+++ b/src/lib/components/edit-dialog/edit-location.svelte
@@ -1,3 +1,7 @@
+<!--
+Edit form for Location objects, with an interactive map and basic typeahead search.
+The search uses OSM nominatim for geocoding. See $lib/model/geocoding for more details.
+-->
 <script lang="ts">
   import { Label } from "$lib/components/ui/label";
   import { Map, MapMarker } from "$lib/components/map";
@@ -12,6 +16,7 @@
 
   let address: string = item.address;
 
+  // Location updates reactively when the marker is dragged, but we need to manually update the address field
   function onDrag(item: Geopoint) {
     console.log(item);
     address = item.address.format();
diff --git a/src/lib/components/edit-dialog/edit-shift.svelte b/src/lib/components/edit-dialog/edit-shift.svelte
index ac544930..08d2704b 100644
--- a/src/lib/components/edit-dialog/edit-shift.svelte
+++ b/src/lib/components/edit-dialog/edit-shift.svelte
@@ -1,3 +1,10 @@
+<!--
+Edit form for Shift objects.
+Supports basic patterns (same start-end time every day; current default behavior) and complex
+recurrence patterns (e.g. every 2nd Tuesday of the month).
+The latter turned out to be unnecessary for our users, but it is fully supported in the model.
+(In fact, the simple pattern is just a special case - but don't tell Oz :D)
+-->
 <script lang="ts">
   import { Shift } from "$lib/model";
   import RecurrenceOptionsEdit from "$lib/components/recurrence/recurrence_options_edit.svelte";
@@ -11,15 +18,9 @@
 
   function mkModeSelect(pattern: Recurrence | SimplePattern) {
     if (pattern instanceof Recurrence) {
-      return {
-        value: "complex",
-        label: "Complex",
-      };
+      return { value: "complex", label: "Complex" };
     } else {
-      return {
-        value: "simple",
-        label: "Simple",
-      };
+      return { value: "simple", label: "Simple" };
     }
   }
 
@@ -27,6 +28,7 @@
 </script>
 
 <div class="flex w-full flex-col gap-1.5">
+  <!-- Contracted duration. (Some shifts count for more time than they actually are when calculating pay / hours) -->
   <Label class="font-semibold" for="duration">Contracted Duration</Label>
   <div class="flex flex-row items-center gap-2">
     <TimePicker id="duration" bind:value={item.paidDuration} />
@@ -35,6 +37,7 @@
 </div>
 <div class="flex w-full flex-col gap-1.5">
   <span class="text-sm font-semibold">Pattern</span>
+  <!-- Select simple or complex pattern -->
   <Select.Root
     selected={mkModeSelect($pattern)}
     onSelectedChange={(sel) => {
@@ -59,8 +62,10 @@
   </Select.Root>
 </div>
 {#if $pattern instanceof Recurrence}
+  <!-- For complex patterns, show the recurrence options form -->
   <RecurrenceOptionsEdit bind:recurrence={$pattern.recurrenceOptions} />
 {:else}
+  <!-- For the basic pattern, show pickers for start/end time -->
   <div class="flex w-full flex-col gap-1.5">
     <Label class="font-semibold" for="start">Start Time</Label>
     <TimePicker id="start" bind:value={$pattern.start} />
@@ -69,6 +74,7 @@
     <Label class="font-semibold" for="start">End Time</Label>
     <TimePicker id="start" bind:value={$pattern.end} />
   </div>
+  <!-- Generate a human-friendly description. The `#key` block forces this to re-render when pattern changes. -->
   {#key $pattern}
     <p class="text-muted-foreground">
       Lasts {item.describePattern()} from {item.fmtStartTime()} to {item.fmtEndTime()}
diff --git a/src/lib/components/event-calendar/calendar-example.svelte b/src/lib/components/event-calendar/calendar-example.svelte
index f9b98baa..76209431 100644
--- a/src/lib/components/event-calendar/calendar-example.svelte
+++ b/src/lib/components/event-calendar/calendar-example.svelte
@@ -1,3 +1,6 @@
+<!--
+Usage example for the EventCalendar component.
+-->
 <script lang="ts">
   import { timeFromMinutes, toMinutes } from "$lib/model/temporal/utils";
   import { HashMap } from "$lib/utils";
diff --git a/src/lib/components/event-calendar/day-column.svelte b/src/lib/components/event-calendar/day-column.svelte
index 8958423b..2e0de0d8 100644
--- a/src/lib/components/event-calendar/day-column.svelte
+++ b/src/lib/components/event-calendar/day-column.svelte
@@ -1,3 +1,6 @@
+<!--
+Columns of the calendar, each representing a day
+-->
 <script lang="ts">
   import type { CalendarDate } from "@internationalized/date";
   import DayHeader from "./day-header.svelte";
diff --git a/src/lib/components/event-calendar/day-header.svelte b/src/lib/components/event-calendar/day-header.svelte
index f27bca1d..2723a6df 100644
--- a/src/lib/components/event-calendar/day-header.svelte
+++ b/src/lib/components/event-calendar/day-header.svelte
@@ -1,3 +1,6 @@
+<!--
+Basic header for the columns - just formats the date
+-->
 <script lang="ts">
   import { getLocalTimeZone, type CalendarDate } from "@internationalized/date";
 
@@ -8,11 +11,7 @@
   export let style = "";
   let className = "";
 
-  $: formatter = new Intl.DateTimeFormat(locale, {
-    weekday: "long",
-    day: "numeric",
-    ...options,
-  });
+  $: formatter = new Intl.DateTimeFormat(locale, { weekday: "long", day: "numeric", ...options });
   $: formatted = formatter.format(day.toDate(tzid));
 
   export { className as class };
diff --git a/src/lib/components/event-calendar/event-calendar.svelte b/src/lib/components/event-calendar/event-calendar.svelte
index ab0598df..cf482c64 100644
--- a/src/lib/components/event-calendar/event-calendar.svelte
+++ b/src/lib/components/event-calendar/event-calendar.svelte
@@ -1,3 +1,65 @@
+<!--
+# Headless Event Calendar Component
+
+This component takes child elements which provide a start and end datetime and positions them on a calendar grid automatically.
+It also handles overlapping events by displaying them in multiple sub-columns, similar to how Outlook does.
+The content inside `TimeGridItem` (i.e. child elements) can be any arbitrary Svelte code!
+
+## Usage
+
+Content cards must be wrapped in `TimeGridItem` components that specify a start and end time.
+They are positioned inside columns. Currently, the columns are defined manually - the component handles positioning within one day, but not across days.
+
+For example:
+
+```svelte
+<EventCalendar
+  let:context
+  ...
+>
+  <DayColumn let:tgContext {context} {parseDate("2025-01-01")}>
+    <TimeGridItem {tgContext} start={new Time(9, 0)} end={new Time(12, 0)} class="bg-yellow-500 bg-opacity-30">
+      <div>Hello</div>
+    </TimeGridItem>
+    <TimeGridItem {tgContext} start={new Time(10, 0)} end={new Time(15, 0)} class="bg-yellow-500 bg-opacity-30">
+      <button>Click me!</button>
+    </TimeGridItem>
+    <TimeGridItem {tgContext} start={new Time(12, 0)} end={new Time(18, 0)} class="bg-yellow-500 bg-opacity-30">
+      <p>World</p>
+    </TimeGridItem>
+  </DayColumn>
+  <DayColumn let:tgContext {context} {parseDate("2025-01-02")}>
+    <TimeGridItem {tgContext} start={new Time(9, 30)} end={new Time(12, 0)} class="bg-yellow-500 bg-opacity-30">
+      <div>Column 2</div>
+    </TimeGridItem>
+  </DayColumn>
+</EventCalendar>
+```
+
+This will create 2 lanes for Jan 1st: one for the (9:00-12:00) and (12:00-18:00) events, and one for the (10:00-15:00) event.
+The second column will have a single lane containing the (9:30-12:00) event. 
+Thus, overlapping events are displayed alongside instead of clipping each other.
+
+## Mechanism
+
+To implement the automatic positioning, we use a shared "context" store.
+Parent elements create it and set up callbacks to update the grid when values change.
+Children take a reference to it and mutate it when they are mounted, changed, or removed. 
+The parent calculates their new final positions and updates the context, which children then use to re-render themselves.
+
+## Props
+- `startDate`: The start date of the calendar. This is the first day that will be displayed. DayColumns before this date will be hidden initially.
+- `endDate`: The end date of the calendar.
+- `startTime`: The start time of the calendar. Grid items starting before this time will be clipped.
+- `endTime`: The end time of the calendar. Grid items ending after this time will be clipped.
+- `step`: The resolution of the visible time grid, in minutes. For example, if `step=60`, there will be one row for each hour.
+- `precision`: The resolution of the grid used to position events. Start/end times of child elements are rounded to its nearest multiple.
+- `columnGap`: The gap between columns. Can be a CSS string (e.g. "30px", "2rem") or a number (e.g. 30 - equivalent to "30px").
+- `line`: The width of the lines in the grid. CSS string (e.g. "1px", "2px", "0.5rem"), defaults to "1px".
+- `calendarHeight`: The height of the calendar. CSS string; defaults to "1800px". Overflowing content is scrollable.
+
+See also: time-grid-item.svelte, day-column.svelte, time-grid.svelte
+-->
 <script lang="ts">
   import { CalendarDate, Time } from "@internationalized/date";
   import { ChevronLeft, ChevronRight } from "lucide-svelte";
@@ -14,7 +76,7 @@
   export let step = 30;
   export let precision = 5;
   export let columnGap = "0.5rem";
-  export let innerGap: string | undefined = undefined;
+  // export let innerGap: string | undefined = undefined;
   export let line = "1px";
   export let calendarHeight = "1800px";
   let className = "";
@@ -27,7 +89,7 @@
     step,
     precision,
     columnGap,
-    innerGap,
+    // innerGap,
     line,
   });
   const context: CalendarContext = { props };
@@ -40,7 +102,7 @@
     step,
     precision,
     columnGap,
-    innerGap,
+    // innerGap,
     line,
   });
 
diff --git a/src/lib/components/event-calendar/time-grid-item.svelte b/src/lib/components/event-calendar/time-grid-item.svelte
index 6fb311df..82781baa 100644
--- a/src/lib/components/event-calendar/time-grid-item.svelte
+++ b/src/lib/components/event-calendar/time-grid-item.svelte
@@ -1,3 +1,18 @@
+<!--
+# TimeGridItem
+
+Wrapper for an event on the time addGridLayout. 
+Positioned automatically according to the `start` and `end` props.
+Has a slot that you can fill with anything you want.
+
+## Props
+- `key`: Unique key for the item. Default: `uuid()`. Can be any string/number as long as it is unique and consistent.
+- `start`: The start time of the item. Default: `0:00`.
+- `end`: The end time of the item. Default: `23:59`.
+- `tgContext`: The context of the time grid. This is passed in from the parent component. It contains the props and stores needed to position the item correctly.
+- `class`: Additional Tailwind classes to apply to the item.
+- `style`: Additional CSS styles to apply directly to the container.
+-->
 <script lang="ts">
   import { dtMax, dtMin, minutesBetween } from "$lib/model/temporal/utils";
   import { Time } from "@internationalized/date";
diff --git a/src/lib/components/event-calendar/time-grid.svelte b/src/lib/components/event-calendar/time-grid.svelte
index 00689bfd..4d1513d9 100644
--- a/src/lib/components/event-calendar/time-grid.svelte
+++ b/src/lib/components/event-calendar/time-grid.svelte
@@ -1,3 +1,8 @@
+<!--
+# TimeGrid Component
+
+A grid that positions TimeGridItems on a calendar grid automatically.
+-->
 <script lang="ts">
   import { fmtTime, minutesBetween, toMinutes } from "$lib/model/temporal/utils";
   import { Time } from "@internationalized/date";
@@ -17,12 +22,14 @@
   export let style = "";
   let className = "";
 
+  // Set up the content
   const props = writable<TimeGridProps>({ start, end, step, precision, columnGap, showTime });
   const intervals = writable(new Map<string, { start: Time; end: Time }>());
   const startCols = writable(new Map<string, number>());
   const endCols = writable(new Map<string, number>());
   export const tgContext: TimeGridContext = { props, intervals, startCols, endCols };
 
+  // Reactive variables
   $: tgContext.props.set({ start, end, step, precision, columnGap, showTime });
   $: rows = Math.ceil(minutesBetween(start, end) / precision);
   $: visibleRows = Math.ceil(minutesBetween(start, end) / step);
@@ -30,6 +37,7 @@
   $: colVals = Array.from($startCols.values());
   $: cols = Math.max(...colVals, 0);
 
+  // Fires every time the intervals change (i.e. any event is added, rescheduled, or removed)
   tgContext.intervals.subscribe((val) => {
     interface Event {
       key: string;
@@ -37,23 +45,25 @@
       end: number;
     }
 
+    // New start and end columns for each event ID. Children will use these to re-position themselves.
     const startCols = new Map<string, number>();
     const endCols = new Map<string, number>();
+
+    // Events with their start and end times in minutes
     const events: Event[] = [];
 
     val.forEach((interval, key) => {
-      events.push({
-        key,
-        start: toMinutes(interval.start),
-        end: toMinutes(interval.end),
-      });
+      events.push({ key, start: toMinutes(interval.start), end: toMinutes(interval.end) });
     });
 
+    // Sort events by start time (ascending), then end time as tie-breaker (descending)
+    // Results in the minimum necessary number of lanes, with longer events to the left (which looks more natural)
     events.sort((a, b) => a.start - b.start || b.end - a.end);
 
     const columns: number[] = [];
     let ongoing: [Event, number][] = [];
 
+    // A basic greedy algorithm to find the columns
     events.forEach((event) => {
       const { key, start, end } = event;
       let thisStartCol = -1; // Starting column for the new event
@@ -116,16 +126,32 @@
 </script>
 
 <div class={className} {style}>
+  <!--
+  Layout is as follows:
+  - Fixed top row for headers
+  - Remaining rows are the time grid
+  - Leftmost column is the time labels, the rest are the grid columns, a final column is added for padding
+
+  Variable meanings:
+  - rows: number of rows in the grid
+  - cols: number of columns in the grid
+  - colGap: gap between columns (currenly not used)
+  - hLineWidth: thickness of the horizontal lines
+  - vLineWidth: thickness of the vertical lines
+  - padRight: padding on the right side of the grid
+  -->
   <div
     class="time-grid"
     style="--rows: {rows}; --cols: {cols}; --colGap: {colGap}; --hLineWidth: {hLineWidth}; --vLineWidth: {vLineWidth ??
       hLineWidth}; --padRight: {padRight}"
   >
     {#each Array.from({ length: visibleRows }) as _, i}
+      <!-- Render the time labels and row lines. Depends on the grid step. -->
       {@const rw = Math.ceil((i * $props.step) / $props.precision) + 2}
       <div class="hline-container" style="grid-row: {rw}; grid-column: 1 / span all">
         <div class="hline"></div>
       </div>
+      <!-- Container for the time label, positioned in column 1 -->
       <div
         class="time-container"
         style="grid-row: {rw}; grid-column: 1; width: {showTime ? 'fit-content' : padLeft}"
@@ -135,11 +161,13 @@
         </span>
       </div>
     {/each}
+    <!-- If the time column isn't hidden, render a vertical line after it -->
     {#if showTime}
       <div class="vline-container" style="grid-row: 1 / span all; grid-column: 1">
         <div class="vline"></div>
       </div>
     {/if}
+    <!-- The rest is our TimeGridItems -->
     <slot {tgContext} />
   </div>
 </div>
diff --git a/src/lib/components/icon/icon.svelte b/src/lib/components/icon/icon.svelte
index 637f00ab..88f2c23b 100644
--- a/src/lib/components/icon/icon.svelte
+++ b/src/lib/components/icon/icon.svelte
@@ -1,17 +1,51 @@
+<!--
+Wrapper for Iconify icons.
+Used with our Icon type. (See $lib/ui/Icon)
+
+## Props
+- `icon`: The icon to display.
+- `inline`: If true, the icon will be positioned inline with the text. Default: false.
+- `width`: The width of the icon (CSS string). Default: "1em".
+- `height`: The height of the icon (CSS string). Default: "1em".
+- `color`: Override the icon color (see below). Default: undefined.
+- `class`: Additional CSS classes to apply to the icon.
+
+## Color
+The possible values for the `color` prop are:
+- `Color` or `string`: always use this color, regardless of the text color or the `icon.color` property.
+- `undefined`: use `icon.color` (if specified) or the text color. (Default)
+- `null`: always use the text color, regardless of the `icon.color` property.
+
+See also: [Iconify docs](https://iconify.design/docs/icon-components/svelte/)
+-->
+
 <script lang="ts">
   import { Icon as TIcon } from "$lib/ui";
   import Icon from "@iconify/svelte";
-  import type Color from "color";
+  import Color from "color";
 
   let icon: TIcon;
   let inline = false;
   let width: string | number = "1em";
   let height: string | number = "1em";
-  let color: Color | undefined = undefined;
+  let color: Color | string | undefined | null = undefined;
   let className = "";
 
+  let clr: string | undefined = undefined;
+  $: {
+    if (color instanceof Color) {
+      clr = color.hex();
+    } else if (typeof color === "string") {
+      clr = color;
+    } else if (color === null) {
+      clr = undefined;
+    } else {
+      clr = icon.color?.hex();
+    }
+  }
+
   // noinspection ReservedWordAsName
   export { icon, inline, width, height, color, className as class };
 </script>
 
-<Icon color={color?.hex()} icon={icon.name} {inline} {width} {height} class={className} />
+<Icon color={clr} icon={icon.name} {inline} {width} {height} class={className} />
diff --git a/src/lib/components/image-picker/icon-picker-content.svelte b/src/lib/components/image-picker/icon-picker-content.svelte
index 7b72c42a..50559b3e 100644
--- a/src/lib/components/image-picker/icon-picker-content.svelte
+++ b/src/lib/components/image-picker/icon-picker-content.svelte
@@ -1,3 +1,10 @@
+<!--
+# Icon Picker Form
+
+Form that allows the user to select any icon from the Iconify API.
+Options are fetched as the user types in the search bar.
+Some pre-defined icons are shown by default.
+-->
 <script lang="ts">
   import { ColorPicker } from "$lib/components/color-picker";
   import { Icon } from "$lib/components/icon";
diff --git a/src/lib/components/image-picker/icon-picker.svelte b/src/lib/components/image-picker/icon-picker.svelte
index 47a97308..07bb5d80 100644
--- a/src/lib/components/image-picker/icon-picker.svelte
+++ b/src/lib/components/image-picker/icon-picker.svelte
@@ -43,7 +43,7 @@
         </Chip>
       {:else}
         <Chip {size} color={icon.color} variant="outline" class="h-fit w-fit p-1">
-          <Icon {icon} slot="icon" class="{PFP_HEIGHT[size]} {PFP_WIDTH[size]}" />
+          <Icon {icon} slot="icon" class="{PFP_HEIGHT[size]} {PFP_WIDTH[size]}" color={null} />
         </Chip>
       {/if}
     </Button>
diff --git a/src/lib/components/image-picker/image-picker.svelte b/src/lib/components/image-picker/image-picker.svelte
index 65e2bcc9..912f34df 100644
--- a/src/lib/components/image-picker/image-picker.svelte
+++ b/src/lib/components/image-picker/image-picker.svelte
@@ -1,3 +1,7 @@
+<!--
+Dropdown to pick `Display.icon` or `Display.avatar`.
+A server is needed to upload the image, so this is not implemented yet.
+-->
 <script lang="ts" generics="T extends Display">
   import IconPickerContent from "./icon-picker-content.svelte";
 
diff --git a/src/lib/components/map/map-marker.svelte b/src/lib/components/map/map-marker.svelte
index ded186bb..fb165de8 100644
--- a/src/lib/components/map/map-marker.svelte
+++ b/src/lib/components/map/map-marker.svelte
@@ -1,3 +1,10 @@
+<!--
+Marker component for displaying a Location or coordinates on the map.
+If draggable, the value can be changed by dragging the marker.
+
+TODO: better docs
+-->
+
 <script lang="ts">
   import { Location } from "$lib/model/core";
   import { Icon } from "$lib/ui";
diff --git a/src/lib/components/map/map.svelte b/src/lib/components/map/map.svelte
index 986d24cd..341848b4 100644
--- a/src/lib/components/map/map.svelte
+++ b/src/lib/components/map/map.svelte
@@ -1,3 +1,8 @@
+<!--
+Displays an interactive OSM map with location markers.
+
+TODO: better docs
+-->
 <script lang="ts">
   import { Location } from "$lib/model";
   import { Geopoint, type LngLat, findBoundingBox } from "$lib/model/geocoding";
diff --git a/src/lib/components/nav-menu/nav-menu.svelte b/src/lib/components/nav-menu/nav-menu.svelte
index f61209f3..49137d05 100644
--- a/src/lib/components/nav-menu/nav-menu.svelte
+++ b/src/lib/components/nav-menu/nav-menu.svelte
@@ -1,3 +1,7 @@
+<!--
+Sidebar component for  navigation.
+TODO: add docs
+-->
 <script lang="ts">
   import { base } from "$app/paths";
   import { page } from "$app/stores";
diff --git a/src/lib/components/profile/profile-picture.svelte b/src/lib/components/profile/profile-picture.svelte
index beb1187e..a7bd4c04 100644
--- a/src/lib/components/profile/profile-picture.svelte
+++ b/src/lib/components/profile/profile-picture.svelte
@@ -28,13 +28,9 @@
       <Avatar.Fallback>{misc.getInitials(item.name)}</Avatar.Fallback>
     </Avatar.Root>
   {:else if item.icon}
-    <Chip
-      {size}
-      color={item.icon.color ?? DEFAULT_COLOR}
-      variant="default"
-      class="my-0.5 {className}"
-    >
-      <IconElement slot="icon" icon={item.icon} />
+    {@const color = item.icon.color ?? DEFAULT_COLOR}
+    <Chip {size} {color} variant="default" class="my-0.5 {className}">
+      <IconElement slot="icon" icon={item.icon} color={null} />
     </Chip>
   {:else if defaultIcon}
     <Chip
@@ -43,7 +39,7 @@
       variant="default"
       class="my-0.5 {className}"
     >
-      <IconElement slot="icon" icon={defaultIcon} />
+      <IconElement slot="icon" icon={defaultIcon} color={null} />
     </Chip>
   {/if}
 {:else if emptyIcon}
@@ -53,7 +49,7 @@
     variant="outline"
     class="my-0.5 {className}"
   >
-    <IconElement slot="icon" icon={emptyIcon} />
+    <IconElement slot="icon" icon={emptyIcon} color={null} />
   </Chip>
 {:else if defaultIcon}
   <Chip
@@ -62,6 +58,6 @@
     variant="outline"
     class="my-0.5 {className}"
   >
-    <IconElement slot="icon" icon={defaultIcon} />
+    <IconElement slot="icon" icon={defaultIcon} color={null} />
   </Chip>
 {/if}
diff --git a/src/lib/components/profile/profile-tooltip.svelte b/src/lib/components/profile/profile-tooltip.svelte
index 1d2e283e..25a0979c 100644
--- a/src/lib/components/profile/profile-tooltip.svelte
+++ b/src/lib/components/profile/profile-tooltip.svelte
@@ -1,3 +1,7 @@
+<!--
+Tooltip that displays when hovering over a profile picture / icon.
+TODO: add docs
+-->
 <script lang="ts" generics="T extends Display">
   import { ProfilePicture } from ".";
 
diff --git a/src/lib/components/profile/profile.svelte b/src/lib/components/profile/profile.svelte
index dd76b3f1..8260b0b9 100644
--- a/src/lib/components/profile/profile.svelte
+++ b/src/lib/components/profile/profile.svelte
@@ -1,3 +1,12 @@
+<!--
+Standard component for displaying anything that implements `Display`.
+The following variants are available:
+- `default`: Displays the profile picture / icon only. Name and description are shown in a tooltip.
+- `text`: Displays the name of the item as a text link. The profile picture / icon is shown in a tooltip.
+- `full`: Displays the profile picture / icon and the name of the item. The description is shown in a tooltip.
+
+TODO: better docs
+-->
 <script lang="ts" generics="T extends Display">
   import * as Tooltip from "$lib/components/ui/tooltip";
   import { Icon, type Display } from "$lib/ui";
diff --git a/src/lib/components/profile/profiles-list.svelte b/src/lib/components/profile/profiles-list.svelte
index 5dd38050..afdfc596 100644
--- a/src/lib/components/profile/profiles-list.svelte
+++ b/src/lib/components/profile/profiles-list.svelte
@@ -1,3 +1,7 @@
+<!--
+Displays multiple displayable items. See also: `profile.svelte` for a single item.
+TODO: better docs
+-->
 <script lang="ts" generics="T extends Display">
   import { Icon, type Display } from "$lib/ui";
   import { v4 as uuid } from "uuid";
diff --git a/src/lib/utils/misc.ts b/src/lib/utils/misc.ts
index 60d81e9b..c8d87b01 100644
--- a/src/lib/utils/misc.ts
+++ b/src/lib/utils/misc.ts
@@ -80,11 +80,7 @@ export function varyColor(
 
 export function randVaryColor(
   col: Color,
-  options: {
-    lightnessSpread?: number;
-    saturationSpread?: number;
-    hueSpread?: number;
-  },
+  options: { lightnessSpread?: number; saturationSpread?: number; hueSpread?: number },
 ): Color {
   const { lightnessSpread = 0, saturationSpread = 0, hueSpread = 0 } = options;
   const { h, s, l } = col.hsl().object();