Refactor code-style

*   Add more docs to JSDoc
*   Add support for `null` in input of API types

Author: wooorm

lib/atom.js

@@ -14,11 +14,12 @@ import {toAuthor, toDate} from './util.js'
 
 /**
  * Build an Atom feed.
+ *
  * Same API as `rss` otherwise.
  *
  * @param {Channel} channel
  *   Data on the feed (the group of items).
- * @param {Array<Entry>} [data]
+ * @param {Array<Entry> | null | undefined} [data]
  *   List of entries.
  * @returns {Root}
  *   Atom feed.

lib/rss.js

@@ -13,11 +13,12 @@ import {toAuthor, toDate} from './util.js'
 
 /**
  * Build an RSS feed.
+ *
  * Same API as `atom` otherwise.
  *
  * @param {Channel} channel
  *   Data on the feed (the group of items).
- * @param {Array<Entry>} [data]
+ * @param {Array<Entry> | null | undefined} [data]
  *   List of entries.
  * @returns {Root}
  *   RSS feed.
@@ -26,8 +27,8 @@ export function rss(channel, data) {
   const now = new Date()
   /** @type {Channel} */
   const meta = channel || {title: null, url: null}
-  /** @type {boolean|undefined} */
-  let atom
+  /** @type {boolean} */
+  let atom = false
 
   if (meta.title === undefined || meta.title === null) {
     throw new Error('Expected `channel.title` to be set')

lib/types.js

@@ -3,9 +3,9 @@
  *   An author object
  * @property {string} name
  *   Example: `'Acme, Inc.'` or `'Jane Doe'`
- * @property {string|undefined} [email]
+ * @property {string | null | undefined} [email]
  *   Example: `john@example.org`
- * @property {string|undefined} [url]
+ * @property {string | null | undefined} [url]
  *   Example: `'https://example.org/john'`.
  *   `url` is used in `atom`, not in `rss`.
  *
@@ -26,57 +26,57 @@
  * @property {string} url
  *   Full URL to the site (required, example:
  *   `'https://www.theguardian.com/world/zimbabwe'`).
- * @property {string|undefined} [feedUrl]
+ * @property {string | null | undefined} [feedUrl]
  *   Full URL to this channel (example:
  *   `'https://www.adweek.com/feed/'`).
  *   Make sure to pass different ones to `rss` and `atom`!
  *   You *should* define this.
- * @property {string|undefined} [description]
+ * @property {string | null | undefined} [description]
  *   Short description of the channel (example: `Album Reviews`).
  *   You *should* define this.
- * @property {string|undefined} [lang]
+ * @property {string | null | undefined} [lang]
  *   BCP 47 language tag representing the language of the whole channel (example:
  *   `'fr-BE'`).
  *   You *should* define this.
- * @property {string|Author|undefined} [author] Optional author of the whole channel.
+ * @property {string | Author | null | undefined} [author] Optional author of the whole channel.
  *   Either `string`, in which case it’s as passing `{name: string}`.
  *   Or an author object.
- * @property {Array<string>|undefined} [tags] Categories of the channel (example:
+ * @property {Array<string> | null | undefined} [tags] Categories of the channel (example:
  *   `['JavaScript', 'React']`).
  *
  * @typedef Entry
  *   Data on a single item.
- * @property {string|undefined} [title]
+ * @property {string | null | undefined} [title]
  *   Title of the item (example: `'Playboi Carti: Whole Lotta Red'`).
  *   Either `title`, `description`, or `descriptionHtml` must be set.
- * @property {string|undefined} [description]
+ * @property {string | null | undefined} [description]
  *   Either the whole post or an excerpt of it (example: `'Lorem'`).
  *   Should be plain text.
  *   `descriptionHtml` is preferred over plain text `description`.
  *   Either `title`, `description`, or `descriptionHtml` must be set.
- * @property {string|undefined} [descriptionHtml]
+ * @property {string | null | undefined} [descriptionHtml]
  *   Either the whole post or an excerpt of it (example: `'<p>Lorem</p>'`).
  *   Should be serialized HTML.
  *   `descriptionHtml` is preferred over plain text `description`.
  *   Either `title`, `description`, or `descriptionHtml` must be set.
- * @property {string|Author|undefined} [author]
+ * @property {string | Author | null | undefined} [author]
  *   Entry version of `channel.author`.
  *   You *should* define this.
  *   For `atom`, it is required to either set `channel.author` or set `author`
  *   on all entries.
- * @property {string|undefined} [url]
+ * @property {string | null | undefined} [url]
  *   Full URL of this entry on the *site* (example:
  *   `'https://pitchfork.com/reviews/albums/roberta-flack-first-take'`).
- * @property {Date|number|string|undefined} [published]
+ * @property {Date | number | string | null | undefined} [published]
  *   When the entry was first published (`Date` or value for `new Date(x)`,
  *   optional).
- * @property {Date|number|string|undefined} [modified]
+ * @property {Date | number | string | null | undefined} [modified]
  *   When the entry was last modified (`Date` or value for `new Date(x)`,
  *   optional).
- * @property {Array<string>|undefined} [tags]
+ * @property {Array<string> | null | undefined} [tags]
  *   Categories of the entry (`Array<string>?`, example:
  *   `['laravel', 'debugging']`).
- * @property {Enclosure|undefined} [enclosure]
+ * @property {Enclosure | null | undefined} [enclosure]
  *   Attached media.
  */
 

lib/util.js

@@ -3,8 +3,12 @@
  */
 
 /**
- * @param {Author|string} value
+ * Create an author object.
+ *
+ * @param {Author | string} value
+ *   Author or string.
  * @returns {Author}
+ *   Valid author.
  */
 export function toAuthor(value) {
   if (typeof value === 'string') {
@@ -19,8 +23,12 @@ export function toAuthor(value) {
 }
 
 /**
- * @param {Date|string|number} value
+ * Create a date object.
+ *
+ * @param {Date | string | number} value
+ *   Serialized date, numeric date, actual date.
  * @returns {Date}
+ *   Valid date.
  */
 export function toDate(value) {
   /* c8 ignore next */

test.js

@@ -5,7 +5,7 @@ import {atom, rss} from './index.js'
 const ODate = global.Date
 
 // @ts-expect-error
-global.Date = function (/** @type {string|number} */ value) {
+global.Date = function (/** @type {string | number} */ value) {
   return new ODate(value || 1_234_567_890_123)
 }