docs(ics): properly documents alarms and durations #178

README.md

@@ -32,11 +32,11 @@
 
 ## Documentation
 
-[Read the docs →](https://datebook.dev/docs/)
+[Read the docs →](https://datebook.dev/start)
 
 ## Demo
 
-Try the [online calendar generators →](https://datebook.dev/generators/)
+Try the [online calendar generator →](https://datebook.dev/generator/)
 
 ## Quick Start
 
@@ -87,14 +87,15 @@ const icalendar = new ICalendar(config)
 ```ts
 icalendar
   .addAlarm({
+    action: 'DISPLAY',
     description: 'Remember this event'
     trigger: {
       minutes: 10
     }
   })
 ```
 
-This will add a [reminder](https://datebook.dev/docs/) that shows 10 minutes before the event.
+This will add a [reminder alarm](https://datebook.dev/config/alarms.html) that shows 10 minutes before the event.
 
 ##### With multiple events
 
@@ -112,23 +113,23 @@ const secondEvent = new ICalendar({
 icalendar.addEvent(secondEvent)
 ```
 
-This will add a [second event](https://datebook.dev/docs/icalendar.html#addevent-icalendar-icalendar) to the same `.ics` file.
+This will add a [second event](https://datebook.dev/api/icalendar.html#addevent-icalendar-icalendar) to the same `.ics` file.
 
 ##### Adding other ICS properties
 
 ```ts
 icalendar.addProperty('CATEGORIES', 'MEETINGS,MANAGEMENT')
 ```
 
-This will [add the `CATEGORIES` ICS property](https://datebook.dev/docs/icalendar.html#addproperty-key-string-value-icspropertyvalue) to the iCalendar instance.
+This will [add the `CATEGORIES` ICS property](https://datebook.dev/api/icalendar.html#addproperty-key-string-value-icspropertyvalue) to the iCalendar instance.
 
 ##### Downloading
 
 ```ts
 icalendar.download()
 ```
 
-This will [download](https://datebook.dev/docs/icalendar.html#download) `Happy Hour.ics` onto the user's device. On most mobile devices, this will open the default calendar app with the event.
+This will [download](https://datebook.dev/api/icalendar.html#download) `Happy Hour.ics` onto the user's device. On most mobile devices, this will open the default calendar app with the event.
 
 #### Google Calendar
 
@@ -138,7 +139,7 @@ const googleCalendar = new GoogleCalendar(config)
 googleCalendar.render()
 ```
 
-[`googleCalendar.render()`](https://datebook.dev/docs/google.html#render) will return a URL that the user can navigate to and pre-fill event details:
+[`googleCalendar.render()`](https://datebook.dev/api/google.html#render) will return a URL that the user can navigate to and pre-fill event details:
 
 ```
 https://calendar.google.com/calendar/render?action=TEMPLATE&text=Happy%20Hour&details=Let's%20blow%20off%20some%20steam%20with%20a%20tall%20cold%20one!&location=The%20Bar%2C%20New%20York%2C%20NY&dates=20220708T190000%2F20220708T230000&recur=RRULE%3AFREQ%3DWEEKLY%3BINTERVAL%3D1

docs/.vuepress/config.ts

@@ -64,7 +64,7 @@ export default defineUserConfig({
           },
           {
             text: 'Attendees',
-            link: '/config/axttendees.md'
+            link: '/config/attendees.md'
           },
           {
             text: 'Recurrences',

docs/README.md

@@ -2,7 +2,7 @@
 home: true
 heroImage: /assets/logo.svg
 actionText: Read the docs →
-actionLink: /docs/
+actionLink: /start
 footer: © 2023 Datebook.
 ---
 

docs/config/alarms.md

@@ -1,6 +1,6 @@
 # Alarms <Badge text="6.0.0" vertical="middle" />
 
-`ICSAlarm`s are used for [iCalendar event alarms](../docs/icalendar.md#addalarmalarm-alarm-badge-text"600"-vertical"middle") and are often used for reminders before an event occurs.
+`ICSAlarm`s are used for [iCalendar event alarms](../api/icalendar.md#addalarm-alarm-alarm) and are often used for reminders before an event occurs.
 
 ### Example
 

src/types/CalendarAttendee.ts

@@ -1,8 +1,8 @@
 import ICSAttendeeOptions from './ICSAttendeeOptions'
+
 /**
  * Basic Attendee Object
  */
-
 type CalendarAttendee = {
     /** The attendee's email address */
     email: string
@@ -12,4 +12,4 @@ type CalendarAttendee = {
     icsOptions?: ICSAttendeeOptions
 }
 
-export default CalendarAttendee
+export default CalendarAttendee

src/types/ICSAlarm.ts

@@ -1,13 +1,23 @@
 import ICSAttachment from './ICSAttachment'
 import ICSDuration from './ICSDuration'
 
+/**
+ * Event alarm/reminder configuration.
+ */
 type ICSAlarm = {
+  /** Determines how the alarm will behave. */
   action: string
-  trigger: ICSDuration | Date,
+  /** When to trigger the alarm. This can be an {@link ICSDuration} object representing the time to display before or after an event, or a valid Date reference. */
+  trigger: ICSDuration | Date
+  /** The full description for the alarm. */
   description?: string
+  /** The short summary for the alarm. */
   summary?: string
+  /** The number of times to repeat the alarm. */
   repeat?: number
+  /** How long the alarm should be present for. */
   duration?: ICSDuration
+  /** Optional file to attach to the alarm. See {@link https://www.kanzaki.com/docs/ical/attach.html} for more info. */
   attach?: ICSAttachment
 }
 

src/types/ICSAttachment.ts

@@ -1,5 +1,11 @@
+/**
+ * Optional file to attach to the alarm.
+ * See {@link https://www.kanzaki.com/docs/ical/attach.html} for more info.
+ */
 type ICSAttachment = {
+  /** iCalendar file attachment properties. */
   params?: string
+  /** URL to the file attachment. */
   url: string
 }
 

src/types/ICSAttendeeOptions.ts

@@ -1,15 +1,17 @@
 /**
- * advanced attendee options for use with the ics format
+ * Advanced attendee options for use with the ICS format.
  */
-
- // TODO comments on props
- // TODO: Consult @jshor about modifications to this hierarchy to accommodate OWA
 type ICSAttendeeOptions = {
-    partStat?: string
-    role?: string
-    rsvp?: boolean
-    delegatedFrom?: string
-    sentBy?: string
+  /** The participation status (RFC-2445 value) of the attendee. */
+  partStat?: string
+  /** The participation role (RFC-2445 value) of the attendee. */
+  role?: string
+  /** Whether or not the attendee is RSVP'd to the event. */
+  rsvp?: boolean
+  /** The delegatee of the attendee request. See {@link https://www.kanzaki.com/docs/ical/delegatedFrom.html} for more info.  */
+  delegatedFrom?: string
+  /** The event sender. See {@link https://www.kanzaki.com/docs/ical/sentBy.html} for more info. */
+  sentBy?: string
 }
 
-export default ICSAttendeeOptions
+export default ICSAttendeeOptions

src/types/ICSDuration.ts

@@ -1,12 +1,19 @@
 /**
- *
+ * Represents timespans before or after an iCalendar event date.
+ * They can be used to trigger alarms.
  */
 type ICSDuration = {
+  /** If `true`, sets the duration to be after the event date. Otherwise, it defaults to before the date (a negative duration). */
   after?: boolean
+  /** The number of weeks the duration spans. */
   weeks?: number
+  /** The number of days the duration spans. */
   days?: number
+  /** The number of hours the duration spans. */
   hours?: number
+  /** The number of minutes the duration spans. */
   minutes?: number
+  /** The number of seconds the duration spans. */
   seconds?: number
 }