From bce35f7c186ce96afffc0a5ecf99949a4cb77952 Mon Sep 17 00:00:00 2001
From: Sebastian Pekarek <mail@sebbo.net>
Date: Mon, 12 Feb 2024 20:44:58 +0100
Subject: [PATCH] docs: Add more examples to code docs

---
 src/calendar.ts |  59 +++++++++++++-
 src/event.ts    | 202 +++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 255 insertions(+), 6 deletions(-)

diff --git a/src/calendar.ts b/src/calendar.ts
index 6b8122140..73bad6408 100755
--- a/src/calendar.ts
+++ b/src/calendar.ts
@@ -89,7 +89,7 @@ export default class ICalCalendar {
     private readonly data: ICalCalendarInternalData;
 
     /**
-     * You can pass options to setup your calendar or use setters to do this.
+     * You can pass options to set up your calendar or use setters to do this.
      *
      * ```javascript
      *  * import ical from 'ical-generator';
@@ -110,6 +110,16 @@ export default class ICalCalendar {
      * cal.name('sebbo.net');
      * ```
      *
+     * `cal.toString()` would then produce the following string:
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * NAME:sebbo.net
+     * X-WR-CALNAME:sebbo.net
+     * END:VCALENDAR
+     * ```
+     *
      * @param data Calendar data
      */
     constructor(data: ICalCalendarData = {}) {
@@ -161,6 +171,11 @@ export default class ICalCalendar {
      * });
      * ```
      *
+     * `cal.toString()` would then produce the following string:
+     * ```text
+     * PRODID:-//My Company//My Product//EN
+     * ```
+     *
      * @since 0.2.0
      */
     prodId(prodId: ICalCalendarProdIdData | string): this;
@@ -206,6 +221,8 @@ export default class ICalCalendar {
      * #### Typescript Example
      * ```typescript
      * import {ICalCalendarMethod} from 'ical-generator';
+     *
+     * // METHOD:PUBLISH
      * calendar.method(ICalCalendarMethod.PUBLISH);
      * ```
      *
@@ -236,6 +253,24 @@ export default class ICalCalendar {
      * Set your feed's name. Is used to fill `NAME`
      * and `X-WR-CALNAME` in your iCal file.
      *
+     * ```typescript
+     * import ical from 'ical-generator';
+     *
+     * const cal = ical();
+     * cal.name('Next Arrivals');
+     *
+     * cal.toString();
+     * ```
+     *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * NAME:Next Arrivals
+     * X-WR-CALNAME:Next Arrivals
+     * END:VCALENDAR
+     * ```
+     *
      * @since 0.2.0
      */
     name(name: string | null): this;
@@ -312,7 +347,7 @@ export default class ICalCalendar {
      * import ical from 'ical-generator';
      * import {getVtimezoneComponent} from '@touch4it/ical-timezones';
      *
-     * const cal = new ICalCalendar();
+     * const cal = ical();
      * cal.timezone({
      *     name: 'FOO',
      *     generator: getVtimezoneComponent
@@ -363,6 +398,10 @@ export default class ICalCalendar {
      * cal.source('http://example.com/my/original_source.ical');
      * ```
      *
+     * ```text
+     * SOURCE;VALUE=URI:http://example.com/my/original_source.ical
+     * ```
+     *
      * @since 2.2.0-develop.1
      */
     source(source: string | null): this;
@@ -595,6 +634,14 @@ export default class ICalCalendar {
      * });
      * ```
      *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * X-MY-CUSTOM-ATTR:1337!
+     * END:VCALENDAR
+     * ```
+     *
      * @since 1.9.0
      */
     x (keyOrArray: {key: string, value: string}[] | [string, string][] | Record<string, string>): this;
@@ -608,6 +655,14 @@ export default class ICalCalendar {
      * calendar.x("X-MY-CUSTOM-ATTR", "1337!");
      * ```
      *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * X-MY-CUSTOM-ATTR:1337!
+     * END:VCALENDAR
+     * ```
+     *
      * @since 1.9.0
      */
     x (keyOrArray: string, value: string): this;
diff --git a/src/event.ts b/src/event.ts
index 684917d9d..cecb092ed 100755
--- a/src/event.ts
+++ b/src/event.ts
@@ -326,6 +326,35 @@ export default class ICalEvent {
      * [Readme](https://github.com/sebbo2002/ical-generator#-date-time--timezones)
      * for details about supported values and timezone handling.
      *
+     * ```typescript
+     * import ical from 'ical-generator';
+     *
+     * const cal = ical();
+     *
+     * const event = cal.createEvent({
+     *   start: new Date('2020-01-01')
+     * });
+     *
+     * // overwrites old start date
+     * event.start(new Date('2024-02-01'));
+     *
+     * cal.toString();
+     * ```
+     *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * BEGIN:VEVENT
+     * UID:7e2aee64-b07a-4256-9b3e-e9eaa452bac8
+     * SEQUENCE:0
+     * DTSTAMP:20240212T190915Z
+     * DTSTART:20240201T000000Z
+     * SUMMARY:
+     * END:VEVENT
+     * END:VCALENDAR
+     * ```
+     *
      * @since 0.2.0
      */
     start(start: ICalDateTimeValue): this;
@@ -513,6 +542,36 @@ export default class ICalEvent {
      * event.allDay(true); // → appointment is for the whole day
      * ```
      *
+     * ```typescript
+     * import ical from 'ical-generator';
+     *
+     * const cal = ical();
+     *
+     * cal.createEvent({
+     *   start: new Date('2020-01-01'),
+     *   summary: 'Very Important Day',
+     *   allDay: true
+     * });
+     *
+     * cal.toString();
+     * ```
+     *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * BEGIN:VEVENT
+     * UID:1964fe8d-32c5-4f2a-bd62-7d9d7de5992b
+     * SEQUENCE:0
+     * DTSTAMP:20240212T191956Z
+     * DTSTART;VALUE=DATE:20200101
+     * X-MICROSOFT-CDO-ALLDAYEVENT:TRUE
+     * X-MICROSOFT-MSNCALENDAR-ALLDAYEVENT:TRUE
+     * SUMMARY:Very Important Day
+     * END:VEVENT
+     * END:VCALENDAR
+     * ```
+     *
      * @since 0.2.0
      */
     allDay(allDay: boolean): this;
@@ -537,6 +596,34 @@ export default class ICalEvent {
      * Events whose floating flag is set to true always take place at the
      * same time, regardless of the time zone.
      *
+     * ```typescript
+     * import ical from 'ical-generator';
+     *
+     * const cal = ical();
+     *
+     * cal.createEvent({
+     *   start: new Date('2020-01-01T20:00:00Z'),
+     *   summary: 'Always at 20:00 in every <Timezone',
+     *   floating: true
+     * });
+     *
+     * cal.toString();
+     * ```
+     *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * BEGIN:VEVENT
+     * UID:5d7278f9-ada3-40ef-83d1-23c29ce0a763
+     * SEQUENCE:0
+     * DTSTAMP:20240212T192214Z
+     * DTSTART:20200101T200000
+     * SUMMARY:Always at 20:00 in every <Timezone
+     * END:VEVENT
+     * END:VCALENDAR
+     * ```
+     *
      * @since 0.2.0
      */
     floating(floating?: boolean): this | boolean {
@@ -577,6 +664,40 @@ export default class ICalEvent {
      * });
      * ```
      *
+     * **Example:**
+     *
+     *```typescript
+     * import ical, { ICalEventRepeatingFreq } from 'ical-generator';
+     *
+     * const cal = ical();
+     *
+     * const event = cal.createEvent({
+     *   start: new Date('2020-01-01T20:00:00Z'),
+     *   summary: 'Repeating Event'
+     * });
+     * event.repeating({
+     *   freq: ICalEventRepeatingFreq.WEEKLY,
+     *   count: 4
+     * });
+     *
+     * cal.toString();
+     * ```
+     *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * BEGIN:VEVENT
+     * UID:b80e6a68-c2cd-48f5-b94d-cecc7ce83871
+     * SEQUENCE:0
+     * DTSTAMP:20240212T193646Z
+     * DTSTART:20200101T200000Z
+     * RRULE:FREQ=WEEKLY;COUNT=4
+     * SUMMARY:Repeating Event
+     * END:VEVENT
+     * END:VCALENDAR
+     * ```
+     *
      * @since 0.2.0
      */
     repeating(repeating: ICalRepeatingOptions | null): this;
@@ -584,6 +705,44 @@ export default class ICalEvent {
     /**
      * Set the event's repeating options by passing an [RRule object](https://github.com/jakubroztocil/rrule).
      * @since 2.0.0-develop.5
+     *
+     * ```typescript
+     * import ical from 'ical-generator';
+     * import { datetime, RRule } from 'rrule';
+     *
+     * const cal = ical();
+     *
+     * const event = cal.createEvent({
+     *   start: new Date('2020-01-01T20:00:00Z'),
+     *   summary: 'Repeating Event'
+     * });
+     *
+     * const rule = new RRule({
+     *   freq: RRule.WEEKLY,
+     *   interval: 5,
+     *   byweekday: [RRule.MO, RRule.FR],
+     *   dtstart: datetime(2012, 2, 1, 10, 30),
+     *   until: datetime(2012, 12, 31)
+     * })
+     * event.repeating(rule);
+     *
+     * cal.toString();
+     * ```
+     *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * BEGIN:VEVENT
+     * UID:36585e40-8fa8-460d-af0c-88b6f434030b
+     * SEQUENCE:0
+     * DTSTAMP:20240212T193827Z
+     * DTSTART:20200101T200000Z
+     * RRULE:FREQ=WEEKLY;INTERVAL=5;BYDAY=MO,FR;UNTIL=20121231T000000Z
+     * SUMMARY:Repeating Event
+     * END:VEVENT
+     * END:VCALENDAR
+     * ```
      */
     repeating(repeating: ICalRRuleStub | null): this;
 
@@ -736,6 +895,15 @@ export default class ICalEvent {
      * });
      * ```
      *
+     * ```text
+     * LOCATION:Apple Store Kurfürstendamm\nKurfürstendamm 26\, 10719 Berlin\,
+     *  Deutschland
+     * X-APPLE-STRUCTURED-LOCATION;VALUE=URI;X-ADDRESS=Kurfürstendamm 26\, 10719
+     *   Berlin\, Deutschland;X-APPLE-RADIUS=141.1751386318387;X-TITLE=Apple Store
+     *   Kurfürstendamm:geo:52.50363,13.32865
+     * GEO:52.50363;13.32865
+     * ```
+     *
      * @since 0.2.0
      */
     location(location: ICalLocation | string | null): this;
@@ -778,11 +946,16 @@ export default class ICalEvent {
      *
      * ```javascript
      * event.description({
-     *     plain: 'Hello World!';
-     *     html: '<p>Hello World!</p>';
+     *     plain: 'Hello World!',
+     *     html: '<p>Hello World!</p>'
      * });
      * ```
      *
+     * ```text
+     * DESCRIPTION:Hello World!
+     * X-ALT-DESC;FMTTYPE=text/html:<p>Hello World!</p>
+     * ```
+     *
      * @since 0.2.0
      */
     description(description: ICalDescription | string | null): this;
@@ -859,14 +1032,35 @@ export default class ICalEvent {
      * an empty attendee.
      *
      * ```javascript
+     * import ical from 'ical-generator';
+     *
      * const cal = ical();
-     * const event = cal.createEvent();
-     * const attendee = event.createAttendee({email: 'hui@example.com', name: 'Hui'});
+     * const event = cal.createEvent({
+     *   start: new Date()
+     * });
+     *
+     * event.createAttendee({email: 'hui@example.com', name: 'Hui'});
      *
      * // add another attendee
      * event.createAttendee('Buh <buh@example.net>');
      * ```
      *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * BEGIN:VEVENT
+     * UID:b4944f07-98e4-4581-ac80-2589bb20273d
+     * SEQUENCE:0
+     * DTSTAMP:20240212T194232Z
+     * DTSTART:20240212T194232Z
+     * SUMMARY:
+     * ATTENDEE;ROLE=REQ-PARTICIPANT;CN="Hui":MAILTO:hui@example.com
+     * ATTENDEE;ROLE=REQ-PARTICIPANT;CN="Buh":MAILTO:buh@example.net
+     * END:VEVENT
+     * END:VCALENDAR
+     * ```
+     *
      * As with the organizer, you can also add an explicit `mailto` address.
      *
      * ```javascript