more cleanup and comments

src/event-sources/func-event-source.ts

@@ -10,13 +10,14 @@ registerEventSourceDef({
     } else if (typeof raw.events === 'function') {
       return raw.events
     }
+    return null
   },
 
   fetch(arg, success, failure) {
     const dateEnv = arg.calendar.dateEnv
 
     unpromisify(
-      arg.eventSource.meta({ // the function
+      arg.eventSource.meta({ // the function returned from parseMeta
         start: dateEnv.toDate(arg.range.start),
         end: dateEnv.toDate(arg.range.end),
         timeZone: dateEnv.timeZone

src/structs/business-hours.ts

@@ -5,11 +5,13 @@ import { EventInput } from './event'
 import { EventStore, parseEventStore } from './event-store'
 
 /*
+Utils for converting raw business hour input into an EventStore,
+for both rendering and the constraint system.
 */
 
 export type BusinessHoursDef = boolean | EventInput | EventInput[]
 
-const BUSINESS_HOUR_EVENT_DEFAULTS = {
+const DEF_DEFAULTS = {
   startTime: '09:00',
   endTime: '17:00',
   daysOfWeek: [ 1, 2, 3, 4, 5 ], // monday - friday
@@ -35,7 +37,7 @@ function refineInputs(input: BusinessHoursDef, isAllDay: boolean): EventInput[]
   let rawDefs: EventInput[]
 
   if (input === true) {
-    rawDefs = [ {} ] // will get BUSINESS_HOUR_EVENT_DEFAULTS verbatim
+    rawDefs = [ {} ] // will get DEF_DEFAULTS verbatim
   } else if (Array.isArray(input)) {
     // if specifying an array, every sub-definition NEEDS a day-of-week
     rawDefs = input.filter(function(rawDef) {
@@ -43,12 +45,12 @@ function refineInputs(input: BusinessHoursDef, isAllDay: boolean): EventInput[]
     })
   } else if (typeof input === 'object' && input) { // non-null object
     rawDefs = [ input ]
-  } else {
+  } else { // is probably false
     rawDefs = []
   }
 
   rawDefs = rawDefs.map(function(rawDef) {
-    rawDef = assignTo({}, BUSINESS_HOUR_EVENT_DEFAULTS, rawDef)
+    rawDef = assignTo({}, DEF_DEFAULTS, rawDef)
 
     if (isAllDay) {
       rawDef.startTime = null

src/structs/date-span.ts

@@ -3,6 +3,8 @@ import { DateInput, DateEnv } from '../datelib/env'
 import { refineProps } from '../util/misc'
 
 /*
+A data-structure for a date-range that will be visually displayed.
+Contains other metadata like isAllDay, and anything else Components might like to store.
 */
 
 export interface DateSpanInput {

src/structs/drag-meta.ts

@@ -3,6 +3,8 @@ import { refineProps } from '../util/misc'
 import { EventNonDateInput } from '../structs/event'
 
 /*
+Information about what will happen when an external element is dragged-and-dropped
+onto a calendar. Contains information for creating an event.
 */
 
 export interface DragMetaInput extends EventNonDateInput {
@@ -10,14 +12,13 @@ export interface DragMetaInput extends EventNonDateInput {
   duration?: DurationInput
   create?: boolean
   stick?: boolean
-  [extendedProp: string]: any
 }
 
 export interface DragMeta {
   time: Duration | null
   duration: Duration | null
   create: boolean // create an event when dropped?
-  stick: boolean // like addEvent's stick parameter
+  stick: boolean // similar to addEvent's stick parameter
   leftoverProps: object
 }
 

src/structs/event-mutation.ts

@@ -7,16 +7,17 @@ import Calendar from '../Calendar'
 import { computeAlignedDayRange } from '../util/misc'
 
 /*
+A data structure for how to modify an EventDef/EventInstance within an EventStore
 */
 
 export interface EventMutation {
   startDelta?: Duration
   endDelta?: Duration
-  standardProps?: any // for the def
+  standardProps?: any // for the def. should not include extendedProps
   extendedProps?: any // for the def
 }
 
-// applies to ALL defs/instances within the event store
+// applies the mutation to ALL defs/instances within the event store
 export function applyMutationToEventStore(eventStore: EventStore, mutation: EventMutation, calendar: Calendar): EventStore {
   let dest = createEmptyEventStore()
 

src/structs/event-source.ts

@@ -4,9 +4,14 @@ import { refineProps } from '../util/misc'
 import { EventInput } from './event'
 import Calendar from '../Calendar'
 
+/*
+Parsing and normalization of the EventSource data type, which defines how event data is fetched.
+Contains the plugin system for defining new types if event sources.
+*/
+
+export type EventInputTransformer = (eventInput: EventInput) => EventInput | null
 export type EventSourceSuccessHandler = (eventInputs: EventInput[]) => void
 export type EventSourceFailureHandler = (errorObj: any) => void
-export type EventInputTransformer = (eventInput: EventInput) => EventInput | null
 
 export interface EventSourceInput {
   id?: string | number

src/structs/event-store.ts

@@ -5,6 +5,9 @@ import Calendar from '../Calendar'
 import { assignTo } from '../util/object'
 
 /*
+A data structure that encapsulates EventDefs and EventInstances.
+Utils for parsing this data from raw EventInputs.
+Utils for manipulating an EventStore.
 */
 
 export interface EventStore {
@@ -12,23 +15,12 @@ export interface EventStore {
   instances: EventInstanceHash
 }
 
-export function createEmptyEventStore(): EventStore {
-  return { defs: {}, instances: {} }
-}
-
-export function mergeEventStores(store0: EventStore, store1: EventStore): EventStore {
-  return {
-    defs: assignTo({}, store0.defs, store1.defs),
-    instances: assignTo({}, store0.instances, store1.instances)
-  }
-}
-
 export function parseEventStore(
   rawEvents: EventInput[],
   sourceId: string,
   fetchRange: UnzonedRange,
   calendar: Calendar,
-  dest: EventStore = createEmptyEventStore()
+  dest: EventStore = createEmptyEventStore() // specify this arg to append to an existing EventStore
 ): EventStore {
 
   for (let rawEvent of rawEvents) {
@@ -62,6 +54,7 @@ export function parseEventStore(
   return dest
 }
 
+// retrieves events that have the same groupId as the instance specified by `instanceId`
 export function getRelatedEvents(eventStore: EventStore, instanceId: string): EventStore {
   let dest = createEmptyEventStore()
   let eventInstance = eventStore.instances[instanceId]
@@ -92,3 +85,14 @@ export function getRelatedEvents(eventStore: EventStore, instanceId: string): Ev
 
   return dest
 }
+
+export function createEmptyEventStore(): EventStore {
+  return { defs: {}, instances: {} }
+}
+
+export function mergeEventStores(store0: EventStore, store1: EventStore): EventStore {
+  return {
+    defs: assignTo({}, store0.defs, store1.defs),
+    instances: assignTo({}, store0.instances, store1.instances)
+  }
+}

src/structs/event.ts

@@ -6,6 +6,8 @@ import Calendar from '../Calendar'
 import { assignTo } from '../util/object'
 
 /*
+Utils for parsing event-input data. Each util parses a subset of the event-input's data.
+It's up to the caller to stitch them together into an aggregate object like an EventStore.
 */
 
 export type EventRenderingChoice = '' | 'background' | 'inverse-background' | 'none'
@@ -69,6 +71,8 @@ export interface EventInstance {
   forcedEndTzo: number | null
 }
 
+// information about an event's dates.
+// only used as an intermediate object. never stored anywhere.
 export interface EventDateSpan {
   isAllDay: boolean
   hasEnd: boolean

src/structs/recurring-event-simple.ts

@@ -8,6 +8,7 @@ import Calendar from '../Calendar'
 import { EventInput } from './event'
 
 /*
+An implementation of recurring events that only supports every-day or weekly recurrences.
 */
 
 const SIMPLE_RECURRING_PROPS = {

src/structs/recurring-event.ts

@@ -3,6 +3,7 @@ import Calendar from '../Calendar'
 import { EventInput } from './event'
 
 /*
+The plugin system for defining how a recurring event is expanded into individual instances.
 */
 
 export interface RecurringEventDateSpans {
@@ -18,8 +19,13 @@ export type RecurringExpander = (
   leftovers: object
 ) => RecurringEventDateSpans | null
 
+
 let recurringExpanders: RecurringExpander[] = []
 
+export function registerRecurringExpander(expander: RecurringExpander) {
+  recurringExpanders.push(expander)
+}
+
 export function expandRecurring(
   rawEvent: EventInput,
   range: UnzonedRange,
@@ -36,7 +42,3 @@ export function expandRecurring(
 
   return null
 }
-
-export function registerRecurringExpander(expander: RecurringExpander) {
-  recurringExpanders.push(expander)
-}

src/util/misc.ts

@@ -452,6 +452,8 @@ export function refineProps(rawProps: GenericHash, processors: GenericHash, defa
 ----------------------------------------------------------------------------------------------------------------------*/
 
 
+// given a timed range, computes an all-day range that has the same exact duration,
+// but whose start time is aligned with the start of the day.
 export function computeAlignedDayRange(range: UnzonedRange): UnzonedRange {
   let dayCnt = Math.floor(diffDays(range.start, range.end)) || 1
   let start = startOfDay(range.start)
@@ -460,6 +462,7 @@ export function computeAlignedDayRange(range: UnzonedRange): UnzonedRange {
 }
 
 
+// given a timed range, computes an all-day range based on how for the end date bleeds into the next day
 export function computeVisibleDayRange(unzonedRange: UnzonedRange, nextDayThreshold: Duration): UnzonedRange {
   let startDay: DateMarker = startOfDay(unzonedRange.start) // the beginning of the day the range starts
   let end: DateMarker = unzonedRange.end