1 files changed, 77 insertions, 3 deletions

diff --git a/static/types.ts b/static/ts/types.ts
index 64e2c709..a01f6672 100644
--- a/static/types.ts
+++ b/static/ts/types.ts
@@ -1,3 +1,8 @@
+/**
+ * Collection of type information for calendar data.
+ * @module
+ */
+
 export {
     ical_type,
     valid_input_types,
@@ -6,6 +11,8 @@ export {
     ChangeLogEntry
 }
 
+
+/** Name of all valid icalendar types. */
 let all_types = [
     'text',
     'uri',
@@ -23,6 +30,7 @@ let all_types = [
 ]
 
 
+/** The union of all elements in `all_types`. */
 type ical_type
     = 'text'
     | 'uri'
@@ -39,6 +47,10 @@ type ical_type
     | 'boolean'
     | 'unknown'
 
+/**
+ * All known names properties (top level keys) can have.
+ * Such as "calscale", "dtstart", ...
+ */
 let property_names = [
     'calscale', 'method', 'prodid', 'version', 'attach', 'categories',
     'class', 'comment', 'description', 'geo', 'location', 'percent-complete',
@@ -50,6 +62,15 @@ let property_names = [
 ];
 
 
+/**
+ * Which property fields each component can hold.
+ *
+ * ```json
+ * { 'VCALENDAR': ['PRODID', 'VERSION', 'CALSCALE', 'METHOD'],
+ *     ...
+ * }
+ * ```
+ */
 let valid_fields: Map<string, string[]> = new Map([
     ['VCALENDAR', ['PRODID', 'VERSION', 'CALSCALE', 'METHOD']],
     ['VEVENT', ['DTSTAMP', 'UID', 'DTSTART', 'CLASS', 'CREATED',
@@ -83,6 +104,12 @@ let valid_fields: Map<string, string[]> = new Map([
 
 valid_fields.set('DAYLIGHT', valid_fields.get('STANDARD')!);
 
+/**
+   All registered property types for VComponents.
+
+   Note that only some of these are valid for each type of component (VCALENDAR,
+   VEVENT, ...), and that they all support both iana and `x-` extensions.
+ */
 type known_ical_types
     = 'ACTION'
     | 'ATTACH'
@@ -130,6 +157,18 @@ type known_ical_types
     | 'URL'
     | 'VERSION'
 
+/**
+ * Which types are valid to store under each property.
+ * If multiple values are an option for that property, then
+ * the list of possibilities will contain a sub-list (see example).
+ *
+ * ```json
+ * { 'DTSTART': ['date', 'date-time'],
+ *   'CATEGORIES': [['text']],
+ *   ...
+ * }
+ * ```
+ */
 let valid_input_types: Map<string, Array<ical_type | ical_type[]>> =
     new Map([
         ['ACTION', ['text']], // AUDIO|DISPLAY|EMAIL|*other*
@@ -184,25 +223,60 @@ let valid_input_types: Map<string, Array<ical_type | ical_type[]>> =
 // type JCalLine {
 // }
 
-type tagname = 'vevent' | string
-
+/** The UID of a VEvent, to make declarations clearer.  */
 type uid = string
 
 /* TODO is this type correct?
    What really are valid values for any? Does that depend on ical_type? Why is the tail a list?
    What really is the type for the parameter map?
 */
+/* TODO link to RFC 7265 (jCal) */
+/**
+ * Alias for a record consisting of
+ * - the name of the type, as a string
+ * - all parameters of the object, as a `Record<String, any>`
+ * - An `ical_type` value, noting the type of the final field(s)
+ * - and one or more values of the type specified by the third field.
+ */
 type JCalProperty
     = [string, Record<string, any>, ical_type, any]
     | [string, Record<string, any>, ical_type, ...any[]]
 
-type JCal = [tagname, JCalProperty[], JCal[]]
+/**
+   Base type for JCal documents.
+
+   Each VComponent in a JCal document is of this form.
 
+   - The first element is the components type
+     ('vevent', 'vcalendar', ...), in all lower case
+   - The second element is is all properties directly
+     on the component.
+   - The third element is a list of all children.
+*/
+type JCal = [string, JCalProperty[], JCal[]]
+
+/** The xml namespace name for xcalendar */
 const xcal = "urn:ietf:params:xml:ns:icalendar-2.0";
 
+/**
+   An entry into a changelog.
+
+   This is primarily used by VEvent, to track what has happened during a
+   session.
+ */
 interface ChangeLogEntry {
+    /**
+       Type of change
+
+       'property' is used for changes to properties.
+
+       'calendar' is used when the containing calendar of a VEVENT is changed
+    */
     type: 'calendar' | 'property',
+    /** The name of the filed changed */
     name: string,
+    /** The previous value, `null` if just created */
     from: string | null,
+    /** The new value, `null` if removed */
     to: string | null,
 }