Implement .d.ts generation from jsdoc comments

.gitignore

@@ -8,4 +8,5 @@ docs/recur-tester.html
 tools/vzic/
 tools/tzdb/
 tools/libical/
+tools/jsdoc-symbols-temp.json
 coverage/

eslint.config.js

@@ -11,6 +11,7 @@ export default [
       "!test/**/*.{js,cjs}",
       "!tools/scriptutils.js",
       "!tools/ICALTester/**/*.js",
+      "!tools/jsdoc-ical.cjs",
       "!eslint.config.js",
       "!rollup.config.js",
       "!karma.conf.cjs"

jsdoc-prepare.json

@@ -0,0 +1,10 @@
+{
+  "source": {
+    "include": "lib/ical",
+    "includePattern": ".js$"
+  },
+  "plugins": ["tools/jsdoc-collect-types.cjs", "node_modules/jsdoc-tsimport-plugin/index.js"],
+  "opts": {
+    "destination": "docs/api/"
+  }
+}

jsdoc.json

@@ -3,7 +3,7 @@
     "include": "lib/ical",
     "includePattern": ".js$"
   },
-  "plugins": ["plugins/markdown"],
+  "plugins": ["plugins/markdown", "tools/jsdoc-ical.cjs", "node_modules/jsdoc-tsimport-plugin/index.js"],
   "opts": {
     "encoding": "utf8",
     "readme": "README.md",

lib/ical/binary.js

@@ -6,15 +6,14 @@
 /**
  * Represents the BINARY value type, which contains extra methods for encoding and decoding.
  *
- * @class
- * @alias ICAL.Binary
+ * @memberof ICAL
  */
 class Binary {
   /**
    * Creates a binary value from the given string.
    *
    * @param {String} aString        The binary value string
-   * @return {ICAL.Binary}          The binary value instance
+   * @return {Binary}               The binary value instance
    */
   static fromString(aString) {
     return new Binary(aString);

lib/ical/component.js

@@ -17,8 +17,7 @@ const COMPONENT_INDEX = 2;
  * Wraps a jCal component, adding convenience methods to add, remove and update subcomponents and
  * properties.
  *
- * @class
- * @alias ICAL.Component
+ * @memberof ICAL
  */
 class Component {
   /**
@@ -31,11 +30,11 @@ class Component {
   }
 
   /**
-   * Creates a new ICAL.Component instance.
+   * Creates a new Component instance.
    *
    * @param {Array|String} jCal         Raw jCal component data OR name of new
    *                                      component
-   * @param {ICAL.Component} parent     Parent component to associate
+   * @param {Component=} parent     Parent component to associate
    */
   constructor(jCal, parent) {
     if (typeof(jCal) === 'string') {
@@ -82,8 +81,20 @@ class Component {
    */
   _timezoneCache = null;
 
+  /**
+   * @private
+   */
+  _components = null;
+
+  /**
+   * @private
+   */
+  _properties = null;
+
   /**
    * The name of this component
+   *
+   * @type {String}
    * @readonly
    */
   get name() {
@@ -101,6 +112,9 @@ class Component {
     return parentDesign || design.getDesignSet(this.name);
   }
 
+  /**
+   * @private
+   */
   _hydrateComponent(index) {
     if (!this._components) {
       this._components = [];
@@ -120,6 +134,9 @@ class Component {
     return (this._components[index] = comp);
   }
 
+  /**
+   * @private
+   */
   _hydrateProperty(index) {
     if (!this._properties) {
       this._properties = [];
@@ -143,7 +160,7 @@ class Component {
    * Finds first sub component, optionally filtered by name.
    *
    * @param {String=} name        Optional name to filter by
-   * @return {?ICAL.Component}     The found subcomponent
+   * @return {?Component}     The found subcomponent
    */
   getFirstSubcomponent(name) {
     if (name) {
@@ -171,7 +188,7 @@ class Component {
    * Finds all sub components, optionally filtering by name.
    *
    * @param {String=} name            Optional name to filter by
-   * @return {ICAL.Component[]}       The found sub components
+   * @return {Component[]}       The found sub components
    */
   getAllSubcomponents(name) {
     let jCalLen = this.jCal[COMPONENT_INDEX].length;
@@ -226,7 +243,7 @@ class Component {
    * Finds the first property, optionally with the given name.
    *
    * @param {String=} name        Lowercase property name
-   * @return {?ICAL.Property}     The found property
+   * @return {?Property}     The found property
    */
   getFirstProperty(name) {
     if (name) {
@@ -268,7 +285,7 @@ class Component {
    * Get all properties in the component, optionally filtered by name.
    *
    * @param {String=} name        Lowercase property name
-   * @return {ICAL.Property[]}    List of properties
+   * @return {Property[]}    List of properties
    */
   getAllProperties(name) {
     let jCalLen = this.jCal[PROPERTY_INDEX].length;
@@ -298,6 +315,9 @@ class Component {
     }
   }
 
+  /**
+   * @private
+   */
   _removeObjectByIndex(jCalIndex, cache, index) {
     cache = cache || [];
     // remove cached version
@@ -314,6 +334,9 @@ class Component {
     this.jCal[jCalIndex].splice(index, 1);
   }
 
+  /**
+   * @private
+   */
   _removeObject(jCalIndex, cache, nameOrObject) {
     let i = 0;
     let objects = this.jCal[jCalIndex];
@@ -339,6 +362,9 @@ class Component {
     return false;
   }
 
+  /**
+   * @private
+   */
   _removeAllObjects(jCalIndex, cache, name) {
     let cached = this[cache];
 
@@ -359,8 +385,8 @@ class Component {
   /**
    * Adds a single sub component.
    *
-   * @param {ICAL.Component} component        The component to add
-   * @return {ICAL.Component}                 The passed in component
+   * @param {Component} component        The component to add
+   * @return {Component}                 The passed in component
    */
   addSubcomponent(component) {
     if (!this._components) {
@@ -383,7 +409,7 @@ class Component {
    * Removes a single component by name or the instance of a specific
    * component.
    *
-   * @param {ICAL.Component|String} nameOrComp    Name of component, or component
+   * @param {Component|String} nameOrComp    Name of component, or component
    * @return {Boolean}                            True when comp is removed
    */
   removeSubcomponent(nameOrComp) {
@@ -409,8 +435,8 @@ class Component {
   /**
    * Adds an {@link ICAL.Property} to the component.
    *
-   * @param {ICAL.Property} property      The property to add
-   * @return {ICAL.Property}              The passed in property
+   * @param {Property} property      The property to add
+   * @return {Property}              The passed in property
    */
   addProperty(property) {
     if (!(property instanceof Property)) {
@@ -438,7 +464,7 @@ class Component {
    *
    * @param {String}               name         Property name to add
    * @param {String|Number|Object} value        Property value
-   * @return {ICAL.Property}                    The created property
+   * @return {Property}                    The created property
    */
   addPropertyWithValue(name, value) {
     let prop = new Property(name);
@@ -456,7 +482,7 @@ class Component {
    *
    * @param {String}               name         Property name to update
    * @param {String|Number|Object} value        Property value
-   * @return {ICAL.Property}                    The created property
+   * @return {Property}                    The created property
    */
   updatePropertyWithValue(name, value) {
     let prop = this.getFirstProperty(name);
@@ -474,7 +500,7 @@ class Component {
    * Removes a single property by name or the instance of the specific
    * property.
    *
-   * @param {String|ICAL.Property} nameOrProp     Property name or instance to remove
+   * @param {String|Property} nameOrProp     Property name or instance to remove
    * @return {Boolean}                            True, when deleted
    */
   removeProperty(nameOrProp) {
@@ -523,7 +549,7 @@ class Component {
    * matched, returns null.
    *
    * @param {String} tzid     The ID of the time zone to retrieve
-   * @return {ICAL.Timezone}  The time zone corresponding to the ID, or null
+   * @return {Timezone}  The time zone corresponding to the ID, or null
    */
   getTimeZoneByID(tzid) {
     // VTIMEZONE components can only appear as a child of the VCALENDAR

lib/ical/component_parser.js

@@ -33,8 +33,7 @@ import Timezone from "./timezone.js";
  *
  * parser.process(stringOrComponent);
  *
- * @class
- * @alias ICAL.ComponentParser
+ * @memberof ICAL
  */
 class ComponentParser {
   /**
@@ -89,15 +88,15 @@ class ComponentParser {
    * Fired when a top level component (VTIMEZONE) is found
    *
    * @callback
-   * @param {ICAL.Timezone} component     Timezone object
+   * @param {Timezone} component     Timezone object
    */
   ontimezone = /* c8 ignore next */ function(component) {};
 
   /**
    * Fired when a top level component (VEVENT) is found.
    *
    * @callback
-   * @param {ICAL.Event} component    Top level component
+   * @param {Event} component    Top level component
    */
   onevent = /* c8 ignore next */ function(component) {};
 
@@ -107,7 +106,7 @@ class ComponentParser {
    *
    * Events must be registered prior to calling this method.
    *
-   * @param {ICAL.Component|String|Object} ical      The component to process,
+   * @param {Component|String|Object} ical      The component to process,
    *        either in its final form, as a jCal Object, or string representation
    */
   process(ical) {

lib/ical/duration.js

@@ -12,15 +12,14 @@ const DATA_PROPS_TO_COPY = ["weeks", "days", "hours", "minutes", "seconds", "isN
  * This class represents the "duration" value type, with various calculation
  * and manipulation methods.
  *
- * @class
- * @alias ICAL.Duration
+ * @memberof ICAL
  */
 class Duration {
   /**
    * Returns a new ICAL.Duration instance from the passed seconds value.
    *
    * @param {Number} aSeconds       The seconds to create the instance from
-   * @return {ICAL.Duration}        The newly created duration instance
+   * @return {Duration}             The newly created duration instance
    */
   static fromSeconds(aSeconds) {
     return (new Duration()).fromSeconds(aSeconds);
@@ -41,7 +40,7 @@ class Duration {
    * Creates a new {@link ICAL.Duration} instance from the passed string.
    *
    * @param {String} aStr       The string to parse
-   * @return {ICAL.Duration}    The created duration instance
+   * @return {Duration}         The created duration instance
    */
   static fromString(aStr) {
     let pos = 0;
@@ -76,7 +75,7 @@ class Duration {
    * @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 {ICAL.Duration}             The createad duration instance
+   * @return {Duration}                  The createad duration instance
    */
   static fromData(aData) {
     return new Duration(aData);
@@ -159,7 +158,7 @@ class Duration {
   /**
    * Returns a clone of the duration object.
    *
-   * @return {ICAL.Duration}      The cloned object
+   * @return {Duration}      The cloned object
    */
   clone() {
     return Duration.fromData(this);
@@ -182,7 +181,7 @@ class Duration {
    * accordingly.
    *
    * @param {Number} aSeconds     The duration value in seconds
-   * @return {ICAL.Duration}      Returns this instance
+   * @return {Duration}           Returns this instance
    */
   fromSeconds(aSeconds) {
     let secs = Math.abs(aSeconds);
@@ -246,7 +245,7 @@ class Duration {
   /**
    * Compares the duration instance with another one.
    *
-   * @param {ICAL.Duration} aOther        The instance to compare with
+   * @param {Duration} aOther             The instance to compare with
    * @return {Number}                     -1, 0 or 1 for less/equal/greater
    */
   compare(aOther) {