Improve jsdoc for typescript

lib/ical/component.js

@@ -8,14 +8,34 @@ import Timezone from "./timezone.js";
 import ICALParse from "./parse.js";
 import stringify from "./stringify.js";
 import design from "./design.js";
+// needed for typescript type resolution
+// eslint-disable-next-line no-unused-vars
+import Duration from "./duration.js";
+// needed for typescript type resolution
+// eslint-disable-next-line no-unused-vars
+import UtcOffset from "./utc_offset.js";
+// needed for typescript type resolution
+// eslint-disable-next-line no-unused-vars
+import Binary from "./binary.js";
+// needed for typescript type resolution
+// eslint-disable-next-line no-unused-vars
+import Period from "./period.js";
+// needed for typescript type resolution
+// eslint-disable-next-line no-unused-vars
+import Recur from "./recur.js";
+// needed for typescript type resolution
+// eslint-disable-next-line no-unused-vars
+import Time from "./time.js";
 
 /**
  * This lets typescript resolve our custom types in the
  * generated d.ts files (jsdoc typedefs are converted to typescript types).
  * Ignore prevents the typedefs from being documented more than once.
  * @ignore
- * @typedef {import("./types.d.js").designSet} designSet
- * Imports the 'designSet' type from the "types.d.js" module
+ * @typedef {import("./types.js").designSet} designSet
+ * Imports the 'designSet' type from the "types.js" module
+ * @typedef {import("./types.js").Geo} Geo
+ * Imports the 'Geo' type from the "types.js" module
  */
 
 const NAME_INDEX = 0;
@@ -277,8 +297,9 @@ class Component {
   /**
    * Returns first property's value, if available.
    *
-   * @param {String=} name    Lowercase property name
-   * @return {?String}        The found property value.
+   * @param {String=} name                    Lowercase property name
+   * @return {Binary | Duration | Period |
+   * Recur | Time | UtcOffset | Geo | string | null}         The found property value.
    */
   getFirstPropertyValue(name) {
     let prop = this.getFirstProperty(name);

lib/ical/design.js

@@ -17,8 +17,8 @@ import Binary from "./binary.js";
  * generated d.ts files (jsdoc typedefs are converted to typescript types).
  * Ignore prevents the typedefs from being documented more than once.
  * @ignore
- * @typedef {import("./types.d.js").designSet} designSet
- * Imports the 'designSet' type from the "types.d.js" module
+ * @typedef {import("./types.js").designSet} designSet
+ * Imports the 'designSet' type from the "types.js" module
  */
 
 /** @module ICAL.design */

lib/ical/duration.js

@@ -68,14 +68,14 @@ class Duration {
   /**
    * Creates a new ICAL.Duration instance from the given data object.
    *
-   * @param {Object} aData               An object with members of the duration
-   * @param {Number} aData.weeks         Duration in weeks
-   * @param {Number} aData.days          Duration in days
-   * @param {Number} aData.hours         Duration in hours
-   * @param {Number} aData.minutes       Duration in minutes
-   * @param {Number} aData.seconds       Duration in seconds
-   * @param {Boolean} aData.isNegative   If true, the duration is negative
-   * @return {Duration}                  The createad duration instance
+   * @param {Object} aData                An object with members of the duration
+   * @param {Number=} aData.weeks         Duration in weeks
+   * @param {Number=} aData.days          Duration in days
+   * @param {Number=} aData.hours         Duration in hours
+   * @param {Number=} aData.minutes       Duration in minutes
+   * @param {Number=} aData.seconds       Duration in seconds
+   * @param {Boolean=} aData.isNegative   If true, the duration is negative
+   * @return {Duration}                   The createad duration instance
    */
   static fromData(aData) {
     return new Duration(aData);
@@ -84,13 +84,13 @@ class Duration {
   /**
    * Creates a new ICAL.Duration instance.
    *
-   * @param {Object} data               An object with members of the duration
-   * @param {Number} data.weeks         Duration in weeks
-   * @param {Number} data.days          Duration in days
-   * @param {Number} data.hours         Duration in hours
-   * @param {Number} data.minutes       Duration in minutes
-   * @param {Number} data.seconds       Duration in seconds
-   * @param {Boolean} data.isNegative   If true, the duration is negative
+   * @param {Object} data                 An object with members of the duration
+   * @param {Number=} data.weeks          Duration in weeks
+   * @param {Number=} data.days           Duration in days
+   * @param {Number=} data.hours          Duration in hours
+   * @param {Number=} data.minutes        Duration in minutes
+   * @param {Number=} data.seconds        Duration in seconds
+   * @param {Boolean=} data.isNegative    If true, the duration is negative
    */
   constructor(data) {
     this.wrappedJSObject = this;
@@ -212,13 +212,13 @@ class Duration {
   /**
    * Sets up the current instance using members from the passed data object.
    *
-   * @param {Object} aData               An object with members of the duration
-   * @param {Number} aData.weeks         Duration in weeks
-   * @param {Number} aData.days          Duration in days
-   * @param {Number} aData.hours         Duration in hours
-   * @param {Number} aData.minutes       Duration in minutes
-   * @param {Number} aData.seconds       Duration in seconds
-   * @param {Boolean} aData.isNegative   If true, the duration is negative
+   * @param {Object} aData                An object with members of the duration
+   * @param {Number=} aData.weeks         Duration in weeks
+   * @param {Number=} aData.days          Duration in days
+   * @param {Number=} aData.hours         Duration in hours
+   * @param {Number=} aData.minutes       Duration in minutes
+   * @param {Number=} aData.seconds       Duration in seconds
+   * @param {Boolean=} aData.isNegative   If true, the duration is negative
    */
   fromData(aData) {
     for (let prop of DATA_PROPS_TO_COPY) {

lib/ical/event.js

@@ -19,10 +19,10 @@ import RecurExpansion from "./recur_expansion.js";
  * generated d.ts files (jsdoc typedefs are converted to typescript types).
  * Ignore prevents the typedefs from being documented more than once.
  * @ignore
- * @typedef {import("./types.d.js").frequencyValues} frequencyValues
- * Imports the 'frequencyValues' type from the "types.d.js" module
- * @typedef {import("./types.d.js").occurrenceDetails} occurrenceDetails
- * Imports the 'occurrenceDetails' type from the "types.d.js" module
+ * @typedef {import("./types.js").frequencyValues} frequencyValues
+ * Imports the 'frequencyValues' type from the "types.js" module
+ * @typedef {import("./types.js").occurrenceDetails} occurrenceDetails
+ * Imports the 'occurrenceDetails' type from the "types.js" module
  */
 
 /**
@@ -279,7 +279,7 @@ class Event {
    * Builds a recur expansion instance for a specific point in time (defaults
    * to startDate).
    *
-   * @param {Time} startTime     Starting point for expansion
+   * @param {Time=} startTime     Starting point for expansion
    * @return {RecurExpansion}    Expansion object
    */
   iterator(startTime) {

lib/ical/parse.js

@@ -12,10 +12,10 @@ import { unescapedIndexOf } from "./helpers.js";
  * Ignore prevents the typedefs from being documented more than once.
  *
  * @ignore
- * @typedef {import("./types.d.js").parserState} parserState
- * Imports the 'parserState' type from the "types.d.js" module
- * @typedef {import("./types.d.js").designSet} designSet
- * Imports the 'designSet' type from the "types.d.js" module
+ * @typedef {import("./types.js").parserState} parserState
+ * Imports the 'parserState' type from the "types.js" module
+ * @typedef {import("./types.js").designSet} designSet
+ * Imports the 'designSet' type from the "types.js" module
  */
 
 const CHAR = /[^ \t]/;

lib/ical/period.js

@@ -14,8 +14,8 @@ import Property from "./property.js";
  * generated d.ts files (jsdoc typedefs are converted to typescript types).
  * Ignore prevents the typedefs from being documented more than once.
  * @ignore
- * @typedef {import("./types.d.js").jCalComponent} jCalComponent
- * Imports the 'occurrenceDetails' type from the "types.d.js" module
+ * @typedef {import("./types.js").jCalComponent} jCalComponent
+ * Imports the 'occurrenceDetails' type from the "types.js" module
  */
 
 /**

lib/ical/property.js

@@ -9,19 +9,40 @@ const TYPE_INDEX = 2;
 const VALUE_INDEX = 3;
 
 import design from "./design.js";
+import ICALStringify from "./stringify.js";
+import ICALParse from "./parse.js";
+
 // needed for typescript type resolution
 // eslint-disable-next-line no-unused-vars
 import Component from "./component.js";
-import ICALStringify from "./stringify.js";
-import ICALParse from "./parse.js";
+// needed for typescript type resolution
+// eslint-disable-next-line no-unused-vars
+import Duration from "./duration.js";
+// needed for typescript type resolution
+// eslint-disable-next-line no-unused-vars
+import UtcOffset from "./utc_offset.js";
+// needed for typescript type resolution
+// eslint-disable-next-line no-unused-vars
+import Binary from "./binary.js";
+// needed for typescript type resolution
+// eslint-disable-next-line no-unused-vars
+import Period from "./period.js";
+// needed for typescript type resolution
+// eslint-disable-next-line no-unused-vars
+import Recur from "./recur.js";
+// needed for typescript type resolution
+// eslint-disable-next-line no-unused-vars
+import Time from "./time.js";
 
 /**
  * This lets typescript resolve our custom types in the
  * generated d.ts files (jsdoc typedefs are converted to typescript types).
  * Ignore prevents the typedefs from being documented more than once.
  * @ignore
- * @typedef {import("./types.d.js").designSet} designSet
- * Imports the 'designSet' type from the "types.d.js" module
+ * @typedef {import("./types.js").designSet} designSet
+ * Imports the 'designSet' type from the "types.js" module
+ * @typedef {import("./types.js").Geo} Geo
+ * Imports the 'Geo' type from the "types.js" module
  */
 
 /**
@@ -141,7 +162,7 @@ class Property {
    *
    * @private
    * @param {Number} index        The index of the value to hydrate
-   * @return {Object}             The decorated value.
+   * @return {?Object}             The decorated value.
    */
   _hydrateValue(index) {
     if (this._values && this._values[index]) {
@@ -300,7 +321,8 @@ class Property {
   /**
    * Finds the first property value.
    *
-   * @return {String}         First property value
+   * @return {Binary | Duration | Period |
+   * Recur | Time | UtcOffset | Geo | string | null}         First property value
    */
   getFirstValue() {
     return this._hydrateValue(0);

lib/ical/recur.js

@@ -14,10 +14,10 @@ import { strictParseInt, clone } from "./helpers.js";
  * Ignore prevents the typedefs from being documented more than once.
  *
  * @ignore
- * @typedef {import("./types.d.js").weekDay} weekDay
- * Imports the 'weekDay' type from the "types.d.js" module
- * @typedef {import("./types.d.js").frequencyValues} frequencyValues
- * Imports the 'frequencyValues' type from the "types.d.js" module
+ * @typedef {import("./types.js").weekDay} weekDay
+ * Imports the 'weekDay' type from the "types.js" module
+ * @typedef {import("./types.js").frequencyValues} frequencyValues
+ * Imports the 'frequencyValues' type from the "types.js" module
  */
 
 const VALID_DAY_NAMES = /^(SU|MO|TU|WE|TH|FR|SA)$/;
@@ -191,7 +191,22 @@ class Recur {
 
   /**
    * An object holding the BY-parts of the recurrence rule
-   * @type {Object}
+   * @memberof ICAL.Recur
+   * @typedef {Object} byParts
+   * @property {Array.<Number>=} BYSECOND            The seconds for the BYSECOND part
+   * @property {Array.<Number>=} BYMINUTE            The minutes for the BYMINUTE part
+   * @property {Array.<Number>=} BYHOUR              The hours for the BYHOUR part
+   * @property {Array.<String>=} BYDAY               The BYDAY values
+   * @property {Array.<Number>=} BYMONTHDAY          The days for the BYMONTHDAY part
+   * @property {Array.<Number>=} BYYEARDAY           The days for the BYYEARDAY part
+   * @property {Array.<Number>=} BYWEEKNO            The weeks for the BYWEEKNO part
+   * @property {Array.<Number>=} BYMONTH             The month for the BYMONTH part
+   * @property {Array.<Number>=} BYSETPOS            The positionals for the BYSETPOS part
+   */
+
+  /**
+   * An object holding the BY-parts of the recurrence rule
+   * @type {byParts}
    */
   parts = null;
 

lib/ical/recur_iterator.js

@@ -13,8 +13,8 @@ import Time from "./time.js";
  * Ignore prevents the typedefs from being documented more than once.
  *
  * @ignore
- * @typedef {import("./types.d.js").weekDay} weekDay
- * Imports the 'weekDay' type from the "types.d.js" module
+ * @typedef {import("./types.js").weekDay} weekDay
+ * Imports the 'weekDay' type from the "types.js" module
  */
 
 /**

lib/ical/stringify.js

@@ -12,8 +12,8 @@ import { foldline } from "./helpers.js";
  * Ignore prevents the typedefs from being documented more than once.
  *
  * @ignore
- * @typedef {import("./types.d.js").designSet} designSet
- * Imports the 'designSet' type from the "types.d.js" module
+ * @typedef {import("./types.js").designSet} designSet
+ * Imports the 'designSet' type from the "types.js" module
  */
 
 const LINE_ENDING = '\r\n';

lib/ical/time.js

@@ -18,8 +18,8 @@ import { strictParseInt, trunc, pad2 } from "./helpers.js";
  * Ignore prevents the typedefs from being documented more than once.
  *
  * @ignore
- * @typedef {import("./types.d.js").weekDay} weekDay
- * Imports the 'weekDay' type from the "types.d.js" module
+ * @typedef {import("./types.js").weekDay} weekDay
+ * Imports the 'weekDay' type from the "types.js" module
  */
 
 /**
@@ -236,8 +236,8 @@ class Time {
   /**
    * Creates a new ICAL.Time instance from the given Javascript Date.
    *
-   * @param {?Date} aDate     The Javascript Date to read, or null to reset
-   * @param {Boolean} useUTC  If true, the UTC values of the date will be used
+   * @param {?Date} aDate             The Javascript Date to read, or null to reset
+   * @param {Boolean} [useUTC=false]  If true, the UTC values of the date will be used
    */
   static fromJSDate(aDate, useUTC) {
     let tt = new Time();
@@ -488,8 +488,8 @@ class Time {
   /**
    * Set up the current instance from the Javascript date value.
    *
-   * @param {?Date} aDate     The Javascript Date to read, or null to reset
-   * @param {Boolean} useUTC  If true, the UTC values of the date will be used
+   * @param {?Date} aDate             The Javascript Date to read, or null to reset
+   * @param {Boolean} [useUTC=false]  If true, the UTC values of the date will be used
    */
   fromJSDate(aDate, useUTC) {
     if (!aDate) {

lib/ical/timezone_service.js

@@ -57,8 +57,8 @@ const TimezoneService = {
   /**
    * Returns a timezone by its tzid if present.
    *
-   * @param {String} tzid     Timezone identifier (e.g. America/Los_Angeles)
-   * @return {?Timezone}      The timezone, or null if not found
+   * @param {String} tzid               Timezone identifier (e.g. America/Los_Angeles)
+   * @return {Timezone | undefined}     The timezone, or undefined if not found
    */
   get: function(tzid) {
     if (zones === null) {

lib/ical/types.d.js → lib/ical/types.js

@@ -3,11 +3,15 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
  * Portions Copyright (C) Philipp Kewisch, 2024 */
 
+// TODO: Once https://github.com/microsoft/TypeScript/issues/22160 and
+// https://github.com/microsoft/TypeScript/issues/46011 is fixed, update
+// @typedef(import(...)) to @import to avoid re-exporting the typedefs
+
 /* eslint-disable no-unused-vars */
 // needed for typescript type resolution
+import Component from "./component";
 import Event from "./event";
 import Time from "./time";
-import Component from "./component";
 
 /**
  * The weekday, 1 = SUNDAY, 7 = SATURDAY. Access via
@@ -75,4 +79,15 @@ import Component from "./component";
  * @property {boolean} propertyGroups  If content lines may include a group name
  */
 
+/**
+ * The jCal Geo type. This is a tuple representing a geographical location.
+ * The first element is the Latitude and the second element is the Longitude.
+ *
+ * TODO: Properly typedef this when https://github.com/hegemonic/catharsis/pull/70
+ *
+ * @typedef {Array} Geo
+ * @property {Number} 0     Latitude
+ * @property {Number} 1     Longitude
+ */
+
 export const _ = {};