Improve JSDoc and types

Author: Hexagon

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "proper-tags",
   "description": "A few common utility template tags for ES2015",
-  "version": "2.0.0-alpha.1",
+  "version": "2.0.0-alpha.2",
   "author": "Hexagon <https://github.com/hexagon>",
   "bugs": {
     "url": "http://github.com/declandewet/common-tags/issues"

package.json

@@ -2,6 +2,10 @@ import { createTag } from '../createTag/index.js';
 import { stripIndent } from '../stripIndent/index.js';
 import { inlineArrayTransformer } from '../inlineArrayTransformer/index.js';
 
+/**
+ * Allows you to inline an array substitution as a comma-separated list.
+ * @type {TemplateTag}
+ */
 const commaLists = createTag(
   inlineArrayTransformer({ separator: ',' }),
   stripIndent,

src/commaLists/commaLists.js

@@ -2,6 +2,10 @@ import { createTag } from '../createTag/index.js';
 import { stripIndent } from '../stripIndent/index.js';
 import { inlineArrayTransformer } from '../inlineArrayTransformer/index.js';
 
+/**
+ * Allows you to inline an array substitution as a comma-separated list, the last of which is preceded by the word "and".
+ * @type {TemplateTag}
+ */
 const commaListsAnd = createTag(
   inlineArrayTransformer({ separator: ',', conjunction: 'and' }),
   stripIndent,

src/commaListsAnd/commaListsAnd.js

@@ -2,6 +2,10 @@ import { createTag } from '../createTag/index.js';
 import { stripIndent } from '../stripIndent/index.js';
 import { inlineArrayTransformer } from '../inlineArrayTransformer/index.js';
 
+/**
+ * Allows you to inline an array substitution as a comma-separated list, the last of which is preceded by the word "or".
+ * @type {TemplateTag}
+ */
 const commaListsOr = createTag(
   inlineArrayTransformer({ separator: ',', conjunction: 'or' }),
   stripIndent,

src/commaListsOr/commaListsOr.js

@@ -4,6 +4,10 @@ import { inlineArrayTransformer } from '../inlineArrayTransformer/index.js';
 import { splitStringTransformer } from '../splitStringTransformer/index.js';
 import { removeNonPrintingValuesTransformer } from '../removeNonPrintingValuesTransformer/index.js';
 
+/**
+ * An HTML tag function that processes a template literal and returns an HTML string.
+ * @type {TemplateTag}
+ */
 const html = createTag(
   splitStringTransformer('\n'),
   removeNonPrintingValuesTransformer(),

src/html/html.js

@@ -1,5 +1,9 @@
 import { createTag } from '../createTag/index.js';
 
+/**
+ * A no-op tag that might come in useful in some scenarios, e.g. mocking.
+ * @type {TemplateTag}
+ */
 const id = createTag();
 
 export  { id };

src/id/id.js

@@ -1,3 +1,13 @@
+
+/**
+ * JSTag
+ * A function that takes a template literal and returns a string.
+ * @typedef {function} JSTag
+ * @param {TemplateStringsArray} literals - The template literal containing placeholders.
+ * @param {...*} placeholders - The values to replace the placeholders in the template literal.
+ * @returns {string} - The result string after processing the template literal.
+ */
+
 // core
 export { createTag } from "./createTag/index.js";
 

src/index.js

@@ -12,17 +12,37 @@ export class TemplateTag {
      */
     constructor(...transformers: any[]);
 }
-export const html: Function;
-export const commaLists: Function;
-export const commaListsAnd: Function;
-export const commaListsOr: Function;
+/**
+ * An HTML tag function that processes a template literal and returns an HTML string.
+ * @type {TemplateTag}
+ */
+export const html: TemplateTag;
+/**
+ * Allows you to inline an array substitution as a comma-separated list.
+ * @type {TemplateTag}
+ */
+export const commaLists: TemplateTag;
+/**
+ * Allows you to inline an array substitution as a comma-separated list, the last of which is preceded by the word "and".
+ * @type {TemplateTag}
+ */
+export const commaListsAnd: TemplateTag;
+/**
+ * Allows you to inline an array substitution as a comma-separated list, the last of which is preceded by the word "or".
+ * @type {TemplateTag}
+ */
+export const commaListsOr: TemplateTag;
 /**
  * Consumes a pipeline of composable transformer plugins and produces a template tag.
  * @param  {...Object} [...rawTransformers] - An array or arguments list of transformers
  * @return {Function}                       - A template tag
  */
 export function createTag(...rawTransformers: any[]): Function;
-export const id: Function;
+/**
+ * A no-op tag that might come in useful in some scenarios, e.g. mocking.
+ * @type {TemplateTag}
+ */
+export const id: TemplateTag;
 /**
  * Converts an array substitution to a string containing a list
  * @param {String} [opts.separator = '']   - The character that separates each item

types/proper-tags.d.cts

@@ -11,17 +11,37 @@ export class TemplateTag {
      */
     constructor(...transformers: any[]);
 }
-export const html: Function;
-export const commaLists: Function;
-export const commaListsAnd: Function;
-export const commaListsOr: Function;
+/**
+ * An HTML tag function that processes a template literal and returns an HTML string.
+ * @type {TemplateTag}
+ */
+export const html: TemplateTag;
+/**
+ * Allows you to inline an array substitution as a comma-separated list.
+ * @type {TemplateTag}
+ */
+export const commaLists: TemplateTag;
+/**
+ * Allows you to inline an array substitution as a comma-separated list, the last of which is preceded by the word "and".
+ * @type {TemplateTag}
+ */
+export const commaListsAnd: TemplateTag;
+/**
+ * Allows you to inline an array substitution as a comma-separated list, the last of which is preceded by the word "or".
+ * @type {TemplateTag}
+ */
+export const commaListsOr: TemplateTag;
 /**
  * Consumes a pipeline of composable transformer plugins and produces a template tag.
  * @param  {...Object} [...rawTransformers] - An array or arguments list of transformers
  * @return {Function}                       - A template tag
  */
 export function createTag(...rawTransformers: any[]): Function;
-export const id: Function;
+/**
+ * A no-op tag that might come in useful in some scenarios, e.g. mocking.
+ * @type {TemplateTag}
+ */
+export const id: TemplateTag;
 /**
  * Converts an array substitution to a string containing a list
  * @param {String} [opts.separator = '']   - The character that separates each item