server: Add some documentation

src/becca/entities/rows.ts

@@ -38,9 +38,18 @@ export interface RecentNoteRow {
     utcDateCreated?: string;
 }
 
+/**
+ * Database representation of an option.
+ * 
+ * Options are key-value pairs that are used to store information such as user preferences (for example
+ * the current theme, sync server information), but also information about the state of the application).
+ */
 export interface OptionRow {
+    /** The name of the option. */
     name: string;
+    /** The value of the option. */
     value: string;
+    /** `true` if the value should be synced across multiple instances (e.g. locale) or `false` if it should be local-only (e.g. theme). */
     isSynced: boolean;
     utcDateModified?: string;
 }

src/services/options.ts

@@ -1,3 +1,17 @@
+/**
+ * @module
+ * 
+ * Options are key-value pairs that are used to store information such as user preferences (for example
+ * the current theme, sync server information), but also information about the state of the application.
+ * 
+ * Although options internally are represented as strings, their value can be interpreted as a number or
+ * boolean by calling the appropriate methods from this service (e.g. {@link #getOptionInt}).\
+ * 
+ * Generally options are shared across multiple instances of the application via the sync mechanism,
+ * however it is possible to have options that are local to an instance. For example, the user can select
+ * a theme on a device and it will not affect other devices.
+ */
+
 import becca from "../becca/becca.js";
 import BOption from "../becca/entities/boption.js";
 import { OptionRow } from '../becca/entities/rows.js';
@@ -74,6 +88,13 @@ function setOption(name: string, value: string | number | boolean) {
     }
 }
 
+/**
+ * Creates a new option in the database, with the given name, value and whether it should be synced.
+ * 
+ * @param name the name of the option to be created.
+ * @param value the value of the option, as a string. It can then be interpreted as other types such as a number of boolean.
+ * @param isSynced `true` if the value should be synced across multiple instances (e.g. locale) or `false` if it should be local-only (e.g. theme).
+ */
 function createOption(name: string, value: string, isSynced: boolean) {
     new BOption({
         name: name,

src/services/options_init.ts

@@ -65,6 +65,9 @@ async function initNotSyncedOptions(initialized: boolean, theme: string, opts: N
     optionService.createOption('syncProxy', opts.syncProxy || '', false);
 }
 
+/**
+ * Contains all the default options that must be initialized on new and existing databases (at startup). The value can also be determined based on other options, provided they have already been initialized.
+ */
 const defaultOptions: DefaultOption[] = [
     { name: 'revisionSnapshotTimeInterval', value: '600', isSynced: true },
     { name: 'revisionSnapshotNumberLimit', value: '-1', isSynced: true },
@@ -119,6 +122,7 @@ const defaultOptions: DefaultOption[] = [
     { name: 'locale', value: 'en', isSynced: true },
     { name: 'firstDayOfWeek', value: '1', isSynced: true },
 
+    // Code block configuration
     { name: "codeBlockTheme", value: (optionsMap) => {
         if (optionsMap.theme === "light") {
             return "default:stackoverflow-light";
@@ -129,6 +133,11 @@ const defaultOptions: DefaultOption[] = [
     { name: "codeBlockWordWrap", value: "false", isSynced: true }
 ];
 
+/**
+ * Initializes the options, by checking which options from {@link #allDefaultOptions()} are missing and registering them. It will also check some environment variables such as safe mode, to make any necessary adjustments.
+ * 
+ * This method is called regardless of whether a new database is created, or an existing database is used.
+ */
 function initStartupOptions() {
     const optionsMap = optionService.getOptionMap();