Automatic types generation from jsdoc comments (#662)

Generates typescript types from jsdoc comments. Adjustments have been made to ensure the api docs page uses the ICAL. prefix on the types, as this is the intended way to use the library.
kewisch · Jun 13, 2024 · e82ff54 · e82ff54
1 parent eddffb1
commit e82ff54
Show file tree

Hide file tree

Showing 28 changed files with 596 additions and 500 deletions.
diff --git a/.gitignore b/.gitignore
@@ -8,4 +8,5 @@ docs/recur-tester.html
 tools/vzic/
 tools/tzdb/
 tools/libical/
+tools/jsdoc-symbols-temp.json
 coverage/
diff --git a/eslint.config.js b/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"

diff --git a/jsdoc-prepare.json b/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/"
+  }
+}
diff --git a/jsdoc.json b/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",

diff --git a/lib/ical/binary.js b/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);

diff --git a/lib/ical/component.js b/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

diff --git a/lib/ical/component_parser.js b/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) {

diff --git a/lib/ical/duration.js b/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) {