1 files changed, 79 insertions, 7 deletions

diff --git a/static/clock.ts b/static/ts/clock.ts
index bbd15de0..11b2b2c5 100644
--- a/static/clock.ts
+++ b/static/ts/clock.ts
@@ -1,3 +1,20 @@
+/**
+  * Components for working with things which depend on the current time.
+  *
+  * Also introduces two web components:
+  *
+  * ```html
+  * <today-button />
+  * <current-time />
+  * ```
+  *
+  * TODO shouldn't these be defined with the rest of the components?
+  *
+  * TODO why isn't Timebar and SmallCellHighlight also Web Components?
+  *
+  * @module
+  */
+
 export {
     SmallcalCellHighlight, Timebar,
     initialize_clock_components
@@ -5,15 +22,23 @@ export {
 
 import { makeElement, date_to_percent } from './lib'
 
-abstract class Clock {
+/**
+ * Interface for `things` which wants to get updated on a human timescale.
+ */
+export abstract class Clock {
+    /** Called every now and then
+     * @param now Called with the current time
+     */
     abstract update(now: Date): void;
 }
 
-
+/** The (blue) vertical line which show the current time in the current day. */
 class Timebar extends Clock {
 
     // start_time: Date
     // end_time: Date
+
+    /** The bar to update */
     bar_object: HTMLElement | null
 
     constructor(/*start_time: Date, end_time: Date*/) {
@@ -23,7 +48,6 @@ class Timebar extends Clock {
         this.bar_object = null
     }
 
-
     update(now: Date) {
         // if (! (this.start_time <= now.getTime() && now.getTime() < this.end_time))
         //     return;
@@ -46,11 +70,26 @@ class Timebar extends Clock {
     }
 }
 
+/**
+ * Highlights the current date in the small calendar to the side.
+ * Currently directly sets a border
+ *
+ * @TODO{but should preferably set a class instead}.
+*/
 class SmallcalCellHighlight extends Clock {
 
+    /** The calendar which a cell should be highlighted in */
     small_cal: HTMLElement
+    /**
+       The currently highlighted cell, or `null` if no cell should be
+       should be highlighted (such as if a non-current month is selected
+    */
     current_cell: HTMLElement | null
 
+    /**
+     * @param small_cal the DOM-node of the calendar widget. It must support
+     *   querySelector.
+     */
     constructor(small_cal: HTMLElement) {
         super();
         this.small_cal = small_cal;
@@ -75,8 +114,16 @@ class SmallcalCellHighlight extends Clock {
 
 /* -------------------------------------------------- */
 
+/**
+   Base class for custom HTML elements which wants to be updated for a human
+   timescale.
+
+   When creating, the attribute `interval` can be given, which specifies (in
+   seconds) how often the component should be updated.
+*/
 class ClockElement extends HTMLElement {
 
+    /** Javascript timer id. Used if the timer needs to be canceled */
     timer_id: number
 
     constructor() {
@@ -95,14 +142,25 @@ class ClockElement extends HTMLElement {
         this.update(new Date)
     }
 
-    static get observedAttributes() {
-        return ['timer_id']
-    }
-
+    /**
+       Method which is called each "tick" (see interval)
+       @param date
+         The current timestamp when the function is called.
+     */
     update(_: Date) { /* noop */ }
 }
 
 
+/**
+   A "button" which always points to the link "~Y-~m-~d.html".
+
+   This class is bound to the web component <today-button />
+
+   In the backend code, a `/today` endpoint exists. That however requires that
+   we ask the server for the correct URL, and follow a 300 (series) redirect.
+
+   Since the URL:s are stable, it's possible to jump directly to the given page.
+ */
 class TodayButton extends ClockElement {
     a: HTMLAnchorElement;
 
@@ -124,12 +182,26 @@ class TodayButton extends ClockElement {
 }
 
 
+/**
+   A component which displays the current time
+
+   This class is bound to the web component <current-time />
+
+   It currently is hard-coded to display time on the format ~H:~M:~S.
+*/
 class CurrentTime extends ClockElement {
     update(now: Date) {
         this.textContent = now.format('~H:~M:~S')
     }
 }
 
+/**
+   Create Web Components mentioned on this page.
+
+   MUST be called early on in the execution.
+
+   TODO this should be merged with other web component declarations.
+*/
 function initialize_clock_components() {
     customElements.define('today-button', TodayButton)
     customElements.define('current-time', CurrentTime)