11 files changed, 224 insertions, 11 deletions
diff --git a/static/ts/components/changelog.ts b/static/ts/components/changelog.ts
index d08f7cb3..720d1656 100644
--- a/static/ts/components/changelog.ts
+++ b/static/ts/components/changelog.ts
@@ -1,3 +1,14 @@
+/**
+ * `<changelog />`
+ *
+ * Display of a VEvents changelog. @ref{ChangeLogEntry}
+ *
+ * @privateRemarks @anchor{VEventChangelog}
+ *
+ * @category Web Components
+ * @mergeTarget components
+ * @module
+ */
 import { makeElement } from '../lib'
 import { ComponentVEvent } from './vevent'
 import { VEvent } from '../vevent'
diff --git a/static/ts/components/date-time-input.ts b/static/ts/components/date-time-input.ts
index 20e9a505..d1ab5ba1 100644
--- a/static/ts/components/date-time-input.ts
+++ b/static/ts/components/date-time-input.ts
@@ -1,9 +1,30 @@
+/**
+ * `<date-time-input />`
+ *
+ * @category Web Components
+ * @mergeTarget components
+ * @module
+ */
+
 export { DateTimeInput }
 
 import { makeElement, parseDate } from '../lib'
 
-
-/* '<date-time-input />' */
+/**
+ * The HTML component `<date-time-input />`.
+ * An element for input for date-times. Similar to
+ * @example
+ * ```html
+ * <input type="date"/>
+ * <input type="time"/>
+ * ```
+ *
+ * But as a single unit.
+ *
+ * ### Attributes
+ * - dateonly
+ *
+ */
 class DateTimeInput extends /* HTMLInputElement */ HTMLElement {
 
     readonly time: HTMLInputElement;
@@ -54,6 +75,11 @@ class DateTimeInput extends /* HTMLInputElement */ HTMLElement {
         }
     }
 
+    /**
+       Setting this to true disabled the time part of the input, and makes
+       any output only have date components (alternativly, the time component
+       set to zero).
+    */
     get dateonly(): boolean {
         return this.hasAttribute('dateonly');
     }
@@ -74,6 +100,7 @@ class DateTimeInput extends /* HTMLInputElement */ HTMLElement {
         this.dateonly = date.dateonly;
     }
 
+    /** Returns current value as a Date object. */
     get value(): Date {
         let dt;
         let date = this.date.value;
@@ -88,6 +115,7 @@ class DateTimeInput extends /* HTMLInputElement */ HTMLElement {
         return dt;
     }
 
+    /** Returns current value as an ISO-8601 formatted string. */
     get stringValue(): string {
         if (this.dateonly) {
             return this.value.format("~Y-~m-~d")
diff --git a/static/ts/components/edit-rrule.ts b/static/ts/components/edit-rrule.ts
index a361bdee..b78171cc 100644
--- a/static/ts/components/edit-rrule.ts
+++ b/static/ts/components/edit-rrule.ts
@@ -1,3 +1,15 @@
+/**
+ * `<vevent-edit-rrule />`
+ *
+ * An edit form for a recurrence rule. Searches its template for elements
+ * with `[name="<<field name>>"]`, and binds to those.
+ *
+ * TODO rename this file
+ *
+ * @category Web Components
+ * @mergeTarget components
+ * @module
+ */
 export { EditRRule }
 
 import { ComponentVEvent } from './vevent'
diff --git a/static/ts/components/input-list.ts b/static/ts/components/input-list.ts
index 0afd4999..31dd5158 100644
--- a/static/ts/components/input-list.ts
+++ b/static/ts/components/input-list.ts
@@ -1,3 +1,13 @@
+/**
+ * `<input-list />`
+ *
+ * A list of identical input fields, which forms a group. For example
+ * useful to handle keywords.
+ *
+ * @category Web Components
+ * @mergeTarget components
+ * @module
+ */
 export { InputList }
 
 /*
@@ -58,6 +68,10 @@ class InputList extends HTMLElement {
         this.appendChild(new_el);
     }
 
+    /**
+     * The value from each element, except the last which should always be empty.
+     * Has an unspecified type, since children:s value field might give non-strings.
+     */
     get value(): any[] {
         let value_list = []
         for (let child of this.children) {
diff --git a/static/ts/components/popup-element.ts b/static/ts/components/popup-element.ts
index 458f543c..cc011ce3 100644
--- a/static/ts/components/popup-element.ts
+++ b/static/ts/components/popup-element.ts
@@ -1,3 +1,19 @@
+/**
+ * `<popup-element />`
+ *
+ * A (small) floating window containing information, which can be dragged
+ * arround. Consists of a navigation bar with a few buttons for
+ * controlling the window, which also works as a drag handle, along with
+ * an area for contents, which can be resized by the user.
+
+ * Currently tightly coupled to VEvent's, since their color
+ * profile is derived from their owning events calendar, and they have
+ * action buttons for the event in their navigation bar.
+ *
+ * @category Web Components
+ * @mergeTarget components
+ * @module
+ */
 export { PopupElement, setup_popup_element }
 
 import { VEvent } from '../vevent'
@@ -7,12 +23,19 @@ import { ComponentVEvent } from './vevent'
 
 import { remove_event } from '../server_connect'
 
-/* <popup-element /> */
+/**
+   ### Attributes
+   - visible
+   */
 class PopupElement extends ComponentVEvent {
 
     /* The popup which is the "selected" popup.
-    /* Makes the popup last hovered over the selected popup, moving it to
+     * Makes the popup last hovered over the selected popup, moving it to
      * the top, and allowing global keyboard bindings to affect it. */
+    /**
+       The popup which was most recently interacted with by the user. Used to
+       move it on top of all others, as well as sending relevant key events there.
+    */
     static activePopup: PopupElement | null = null;
 
     constructor(uid?: string) {
@@ -81,6 +104,12 @@ class PopupElement extends ComponentVEvent {
         }
     }
 
+    /**
+       If the popup is currently visible.
+
+       Adds the `visible` attribute to the component, which must then be handled
+       through CSS.
+     */
     get visible(): boolean {
         return this.hasAttribute('visible');
     }
@@ -128,6 +157,10 @@ class PopupElement extends ComponentVEvent {
         el.style.removeProperty('height');
     }
 
+    /**
+       Resize the popup window to fill the current viewport (mostly). Is
+       probably bonud to the maximize button in the navigation bar.
+    */
     maximize() {
         /* TODO this assumes that popups are direct decendant of their parent,
            which they really ought to be */
@@ -144,7 +177,8 @@ class PopupElement extends ComponentVEvent {
     }
 }
 
-/* Create a new popup element for the given VEvent, and ready it for editing the
+/**
+   Create a new popup element for the given VEvent, and ready it for editing the
    event. Used when creating event (through the frontend).
    The return value can safely be ignored.
 */
diff --git a/static/ts/components/tab-group-element.ts b/static/ts/components/tab-group-element.ts
index e90997e9..ce532cec 100644
--- a/static/ts/components/tab-group-element.ts
+++ b/static/ts/components/tab-group-element.ts
@@ -1,3 +1,40 @@
+/**
+ * `<tab-group />`
+
+A group of tabs, where only one can be visible at a time.
+
+@privateRemarks TODO which form does the HTML document have? For CSS purposes
+
+Each tab consists of two parts, a label which is used for selecting
+it, and a tab-element, which contains the actual content. These two
+should refer to each other as follows:
+
+@example
+```
++---------------+     +-----------------+
+|   TabLabel    |     |       Tab       |
++---------------+     +-----------------+
+|            id |<----| aria-labelledby |
+| aria-controls |---->|              id |
++---------------+     +-----------------+
+```
+
+Further information about tabs in HTML can be found here:
+https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/Tab_Role
+
+#### CSS Variables
+
+##### tabcount
+Each tab element has the style property `--tabcount` set to how
+many tabs it has. This is mostly useful to make sure the tab context
+is large enough to fit all tab labels without overflowing.
+
+ *
+ * @category Web Components
+ * @mergeTarget components
+ * @module
+ */
+
 import { ComponentVEvent } from './vevent'
 import { makeElement, gensym } from '../lib'
 import { EditRRule } from './edit-rrule'
@@ -6,7 +43,7 @@ import { vcal_objects } from '../globals'
 
 export { TabGroupElement }
 
-/* Lacks a template, since it's trivial
+/** Lacks a template, since it's trivial
    The initial children of this element all becomes tabs, each child may have
    the datapropertys 'label' and 'title' set, where label is what is shown in
    the tab bar, and title is the hower text.
@@ -81,6 +118,12 @@ class TabGroupElement extends ComponentVEvent {
 
     } /* end connectedCallback */
 
+    /**
+       Adds a new tab to the group. The first parameter will make up the body
+       of the tab. The label is whath should be shown in the tab selector,
+       but defaults to the first letter of the text content of the body node.
+       Title is the hoover text of the label.
+    */
     addTab(child: HTMLElement, label?: string, title?: string) {
 
         /* First character of text is a good a guess as any for our label,
@@ -128,6 +171,10 @@ class TabGroupElement extends ComponentVEvent {
         this.style.setProperty('--tabcount', '' + this.tabs.length);
     }
 
+    /**
+       HTMLElement must be one of the tab bodies in this group. This method
+       removes it, along with its TabLabel.
+    */
     removeTab(tab: HTMLElement) {
         let id = tab.getAttribute('aria-labelledby')!
         let label = document.getElementById(id)
diff --git a/static/ts/components/vevent-block.ts b/static/ts/components/vevent-block.ts
index 9bbb8e7e..374cf103 100644
--- a/static/ts/components/vevent-block.ts
+++ b/static/ts/components/vevent-block.ts
@@ -1,3 +1,14 @@
+/**
+ * `<vevent-block />`
+ *
+ * A block in our graphical view.
+ *
+ * Unique in that it works quite differently between the week and month view.
+ *
+ * @category Web Components
+ * @mergeTarget components
+ * @module
+ */
 export { ComponentBlock }
 
 import { ComponentVEvent } from './vevent'
diff --git a/static/ts/components/vevent-description.ts b/static/ts/components/vevent-description.ts
index b44185e7..bf62c10d 100644
--- a/static/ts/components/vevent-description.ts
+++ b/static/ts/components/vevent-description.ts
@@ -1,3 +1,19 @@
+/**
+ * `<vevent-description />`
+
+A text representation of a VEvent. Used as the summary tab of our
+popup windows, and in the sidebar.
+
+When redrawn, it looks for an HTML-tag inside its template having the
+attribute `data-property` matching the properties name. If one is
+found, it looks in the `formatters` table
+({@link formatters}), for a field matching the property value, and
+defaults to the key `default`.
+ *
+ * @category Web Components
+ * @mergeTarget components
+ * @module
+ */
 export { ComponentDescription }
 
 import { VEvent } from '../vevent'
diff --git a/static/ts/components/vevent-dl.ts b/static/ts/components/vevent-dl.ts
index a792c07f..a4b51dd9 100644
--- a/static/ts/components/vevent-dl.ts
+++ b/static/ts/components/vevent-dl.ts
@@ -1,3 +1,15 @@
+/**
+ * `<vevent-dl />`
+ *
+ * A description list of a vevent, used for debugging.
+ *
+ * No guarantees are given about the contents of the data fields, more
+ * than that they are related to the value in question.
+ *
+ * @category Web Components
+ * @mergeTarget components
+ * @module
+ */
 export { VEventDL }
 
 import { ComponentVEvent } from './vevent'
diff --git a/static/ts/components/vevent-edit.ts b/static/ts/components/vevent-edit.ts
index e3b5d105..5dd39ee9 100644
--- a/static/ts/components/vevent-edit.ts
+++ b/static/ts/components/vevent-edit.ts
@@ -1,3 +1,14 @@
+/**
+ * `<vevent-edit />`
+ *
+ * Edit form for a vevent, designed for useful human interaction (and
+ * thereby not being all-encompassing).
+ *
+ * @category Web Components
+ * @mergeTarget components
+ * @module
+ */
+
 export { ComponentEdit }
 
 import { ComponentVEvent } from './vevent'
diff --git a/static/ts/components/vevent.ts b/static/ts/components/vevent.ts
index 7487cbb6..1d400e1e 100644
--- a/static/ts/components/vevent.ts
+++ b/static/ts/components/vevent.ts
@@ -1,18 +1,34 @@
+/**
+ * Root component for all events which content is closely linked to a `VEvent` object
+ *
+ * Lacks an accompaning tag, and shouldn't be directly instanciated.
+ *
+ * Note that many of these assume that their initial children are
+ * configured specifically, that is however not completely documented.
+ *
+ * @category Web Components
+ * @mergeTarget components
+ * @module
+ */
+
 export { ComponentVEvent }
 
 import { vcal_objects } from '../globals'
 import { VEvent } from '../vevent'
 
-/* Root component for all events which content is closely linked to a
-@code{VEvent} object
-
-Lacks an accompaning tag, and shouldn't be directly instanciated.
-*/
 abstract class ComponentVEvent extends HTMLElement {
 
     template?: HTMLTemplateElement
     uid: string
 
+    /**
+     * This registeres itself, but doesn't redraw
+     * We do however redraw in connectedCallback
+
+     * @privateRemarks
+     * TODO what is done in the default constructor,
+     * and the default connectedCallback
+    */
     constructor(uid?: string) {
         super();
         this.template = document.getElementById(this.tagName.toLowerCase()) as HTMLTemplateElement | undefined
@@ -64,6 +80,7 @@ abstract class ComponentVEvent extends HTMLElement {
         }
     }
 
+    /** While abstract for this, @emph{must} be overridden for everyone else */
     abstract redraw(data: VEvent): void
 
 }